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Introduction 


The Ultimate OS/2 Programmer's Manual ls aL complete {efeTence 
guide to programming in the OS/2 environment. This includes OS/2 
function calls; EGA, VGA, and Super VGA displays; and an update 
on the newest OS/2 2.1 additions. The U/f!.mate OS/2 
Progrommer's Manua/ covers both OS/2 full-screen and 
Presentation Manager programming. It also contains a full description 
of many of the functions that you need for device driver 
programming and tells you how to make the most of the memory 
available in this environment. 


This book provides a solid I oundation for low-level programming in 
any language by explaining how particular OS/2 functions work. 
Especially helpful are the discussions of three currently 
undocumented OS/2 function groups: KBD, MOU, and VIO. It also 
provides much heavier coverage of the DOSDevloctl function than 
most books on the market. This makes The U/£!.mote OS/2 
Progrommer's Manua/ unique because it does not force you to learn 
about OS/2 using a language you might not know. It simply provides 
the tools you need to create dazzling applications. 


Who should use this book 


Both beginners and experienced programmers can benefit from The 
U/£!.mote OS/2 Progrommer's Mcmua/. For beginners, this book 
explains how OS/2 works, how to use the OS/2 service routines, 
how to access ROM and OS/2 functions, and what each function 
does. For experienced programmers, this book provides a handy 
reference to the many OS/2 and ROM functions available from any 
language. 


You should be familiar with a programming language to benefit the 
most from this book. I tested all program examples in this book using 
Borland Turbo Assembler and Borland C++ 3.1. I used the standard 
Borland debugger in most cases. If you use any other vendors' 
implementation of C or assembler, you might have to change the 
program examples in this book slightly to make them work properly. 


What this book will do 


This book provides three types of information necessary for 
programming an IBM-compatible computer. First, this book will 
explain how to make maximum use of the OS/2 environment when 
writing programs. Second, this book shows equivalent programs 
written in two of the most popular programming languages. Third, 
this book shows how to mix the different languages to create a single 
program. For example, you could write part of a program to access 
the ROM BIOS using assembly language and design a user interface 
with C. Not only does this book show you how programs in different 
languages work, but it shows you how to integrate different languages 
together within the OS/2 environment. 


Why use Borland compilers? 


Although competing language compilers might offer more features or 
convenience than the Borland compilers for OS/2, I chose to use 
Borland compilers for compatibility reasons. Only Borland offers a 


complete range of compatible language compilers that can work 
together. (Microsoft used to provide this capability but dropped all 
OS/2 support in recent versions of their compiler.) Thus, you can 
write part of your program in assembly language for speed and direct 
access to hardware interrupts and functions, and mix your assembly 
language routines with the more structured C or Pascal languages. 


In addition, the Borland C compiler closely adheres to the ANSI C 
language standards. This means that you can write code using the 
Borland C compiler and port it over to a completely different 
machine. Using compilers that follow language standards ensures that 
this book will always provide relevant, accurate information no matter 
what new changes appear in future compiler versions. 


Equipment used 


Every program in this book is tested on at least two different 
machines. The first machine includes a Hauppauge 80386 
motherboard, 80387 math coprocessor, ATI VGA Wonder card, 
Logitech MouseMan bus mouse, and a Samtron VGA monitor. The 
second machine includes a Hauppauge 80486 motherboard, Video 
Seven VRAM 11 ERGO card, Logitech MouseMan serial mouse, a 
Multisync 3D monitor, a Hitachi 1503S CD-ROM drive, and a 
Creative Labs Sound Blaster board. The software used includes 
Borland compilers along with OS/2 2.1. I made every effort to 
ensure that the program examples work on any computer 
configuration. However, given the ever changing state of computer 
equipment and software, this is not possible to verify. 


If you experience any problems, try running the same program on a 
different computer. If the problem disappears, then you know that 
your computer equipment is at fault. If the problem persists, write to 
me in care of the publisher and let me know so that I can verify the 
problem and find a way around it for the next edition of this book. 
You also can contact me on Compuserve at 75300,576. I really 
would appreciate hearing any comments (both positive and negative) 
or suggestions you might have. 


What this book contains 


Each chap±eT of The Ultimate OS/2 Programmer's Manual discusses 
a particular aspect of OS/2 programming in more detail. Where 
possible, program examples include both assembler and C. Many of 
the low level programming examples require extensive use of 
assembly language. 


-)i(- Chapter 1 : Visiting the OS/2 command line and Workplace 


Shell This chapter provides the you with three different types of 
information. First, it tells you how to automate and enhance the 
OS/2 command-line (character-mode) interface. This includes REXX 
programming and batch files. Second, this chapter tells you how to 
manipulate the Workplace Shell and use the graphical user interface 
to their advantage. This is an important section considering that 
many programmers come from a character-mode background and 
might not feel comfortable with a graphical user interface. Using the 
graphical user interface also means creating test suites using a 
combination of REXX and the Workplace Shell. Finally, we explore 
the Developer Connection for OS/2. This is a CD-ROM containing a 
plethora of programming tools and other aids. The Developer 
Connection for OS/2 provides you with complete access to most of 
IBMs beta software so that you always get advanced notice of new 
technology before it occurs. 


3i(- Chapter 2: Processor commands and interfaces This chapter 


provides detailed explanations for the different microprocessors used 
in the IBM computer family. The chapter covers the 8088/8086, 
80286, 80386, and 80486 along with their respective math 
coprocessors: 8087, 80287, and 80387. It also covers the new 
Pentium processor from Intel. This might be the only book on your 
shelf that contains such extensive information on such a wide variety 
of Intel processors. 


-*- Chapter 3: Video API Chapter 3 describes the video application 


programming interface (API) provided by OS/2. This chapter views 
programming from the business application viewpoint. Because OS/2 
does not allow direct hardware manipulation by "ring 3" applications, 
the programmer must use the tools supplied by the operating system. 


This chapter also assumes that you want to program for the 
Workplace Shell. (The text will note whether the you can use a 
particular call for character and graphics mode applications.) There 
are two main areas addressed by this chapter: drawing functions and 
window message functions. The programmer needs to know how to 
use both to program in OS/2. In addition to these two main topics, 
the chapter also will discuss how to use fonts within an application. 
This includes determining which fonts the application can access as 
well as other topics of interest. 


-*- Chapter 4: Keyboard and mouse APT As with chapter 3, 


chapter 4 assumes that you need to write application programs. This 
means that the application runs at ring 3 and cannot access the 
keyboard or mouse directly. The keyboard sections of the chapter 
assume that the programmer is writing for the character-mode 
interface. The mouse sections assume that the programmer is writing 
for the Workplace Shell. In both cases, the chapter does address the 
needs for programmers creating device drivers and other ring 2 
applications. For example, it is very likely that someone writing a 
device driver will need to use the OS/2 DOSDevloctl functions to 
access the keyboard and/or mouse. 


-*- Chapter 5: Parallel/serial port API This chapter assumes that 


you want to write a low-level routine that might or might not appear 
as part of an application. There is one section for each port type. 
The DOSDevloctl function provides you with very low-level access 
to the port. This usually happens when the developer needs to create 
a device driver or other ring 2 application. However, you can use 
these function calls even if you want to create an application 
program running at ring 3. 


-*- Chapter 6: Disk API This chapter covers the three levels of 


support provided by OS/2 for disk operations. The first layer is the 
disk operating system level. Ring 2 and character mode applications 
use this part of the API. The next two sections assume that you want 
to create a Workplace Shell application. The first section covers 
standard disk operations in a virtual setting. The second section 
covers physical disk operations. 


-*- Chapter 7: Multimedia API Version 2.1 of OS/2 introduces 


multimedia extensions that are similar to those found in Windows NT 
and Windows 3.1. This chapter covers the use of those extensions 
when used to create REXX applications. Chapter 7 is an extension of 
the REXX section of chapter 1. It takes a Workplace Shell application 
approach. Most of the coding samples will concentrate on the sound 
board and CD-ROM drive because these are the two components 
most programmers need to include in their applications. You can 
create any of these applications without buying additional multimedia 
kits; everything used in this chapter comes with a standard OS/2 
installation . 


-)i(- Chapter 8: Memory management Chapter 8 takes a very 


low-level look at OS/2 memory management. Anyone creating an 
OS/2 program could benefit from the material in this chapter. It 
covers memory allocation, protection, virtual memory, and 
segmentation types. The approach taken for this chapter is the 
general OS/2 application. It will provide an equal number of 
application, device driver, and low-level programming examples. At 
least one of the applications includes the Workplace Shell and shows 
how to circumvent any problems with that environment. 


Using Hungarianlstvle nota+ion 


There are several programming conventions used throughout this 
book that might or might not help you in your programming 
endeavors. Both the programming examples and the text use these 
conventions to make it easier to see what task a function or variable 
performs at a glance. An understanding of these conventions will help 
you receive more information from the examples in this book and 
from many programming books in general. In addition, these same 
concepts are equally applicable to C and assembly code. Many 
developers contributed to the form of these conventions by discussing 
them at conferences and on bulletin board systems (BBS). 


The first stage of development for this system was started by Charles 
Simonyi of Microsoft Corporation. He called his system Hungarian 
Notation, and that is what most people call their systems today. 


There are many places that you can obtain a copy of his work, 
including many BBS. This book uses a derivative of that original work 
as outlined in the following paragraphs. You can use this derivative 
within your REXX and OS/2 programs to enhance readability. There 
are four reasons why you should use these naming conventions in 
your programs. 


> Mnemonic value-This allows the programmer to remember 


the name of a variable easily, which is an important 
consideration for team projects. 


> Suggestive value-You might not be the only one modifying 


your code. If you are working on a team project, others in the 
team will most likely at least look at the code you have written. 
Using these conventions will help others understand what you 
mean when using a specific convention. 


> Consistency-A programmer's ability often is viewed as not 


only how efficiently they program or how well the programs 
they create function but how easily another programmer can 
read their code. Using these conventions will help you maintain 
uniform code from one project to another. Other programmers 
can anticipate the value or function of a section of code simply 
by the conventions you use. 


> Speed of decision-In the business world, the speed at which 


you can create and modify code often will determine the level 
of success of a particular venture. Using consistent code 
reduces the time that you spend trying to decide what someone 
meant when creating a variable or function. This reduction in 
decision time will increase the amount of time you have 
available for productive work. 


Function naming conventions 


The following rules will help you understand the conventions used to 
name functions throughout the book: 


> All functions will show their return type. Because C is a 


strongly typed language, this is a very easy task. Even though 
assembler is not strongly typed, the examples in this book will 


make every effort to provide a return type. We will show the 
return type using a standard qualifier. A listing of these 
standard qualifiers appears in the section on variable naming 
conventions . 


> All function names contained within an application are typed in 


lowercase. All library functions appear in a mixture of upper- 
and lowercase with the initial character capitalized. This saves 
other programmers the time and effort of looking for an 
unfamiliar function within your code when it really is part of the 
C library and vice versa. 


> In many cases, a function converts one value to another value. 


To differentiate these functions from functions that perform a 
more generalized task, type the input value, then a 2, then the 
output value. For example, if you were to create a function for 
converting a value from the frequency domain to the time 
domain, you probably would name the function Freq2Time. 


> Always define a function using only one or two standard 


qualifiers. The tendency of some programmers is to use so 
many qualifiers to define a function name that the intent of 
using this practice is circumvented. The purpose of the function 
becomes difficult to determine because of the number of 
qualifiers. 


> It is always convenient to quickly find where a keyword appears 


within the source code. To help in this, always capitalize 
keywords like FOR and SWITCH. 


Using these five rules will make it much easier to determine the 
purpose and origin of the functions you use within a program. 


Variable naming conven+ions 


Variables are one of the hardest parts of a program to understand. 
Unlike functions and procedures, variables are not defined in the 
manual anywhere and few programs have published data dictionaries. 
As a result, there often is a lot of confusion that exists about the 
exact meaning of a variable. There are several ways that you can 


make it easier to understand the variables that you use within a 
program. The following rules are meant as guidelines and are used 
throughout this book: 


> Always prefix a variable with a single lowercase letter indicating 


its type. In most cases, this is the first letter of the variable 
type, so it is easy to remember what letter to use. The 
following examples show the most common prefixes. This does 
not include some of the more esoteric OS/2 prefixes, but it 
should provide you with everything you need for the majority of 
the material in this book: 
• a Array 
• ab Anchor block 
• b Byte (8-bits) 
• bin Bitmap 
• c Count 
• ch Single-byte character 
• d Difference between two instances of a type 
• dc Device context 
• e Element of an array 
• env Environment 
• f Flag 
• fn Function (not a pointer, but the actual function 


reference) 


• gr Group 
• h Handle 
• hh Hugehandle 
• hp Hugepointer(32-bit) 
• ht Help table 
• i Index (used with a variable) 
• ib Index byte (an address offset) 
• id Identifier 
• 1 Long (32-bits) 
• lp Far pointer (32-bit) 
• mq Messagequeue 
• mt Menu table 
• n Numeric 
• np Nearpointer(16-bit) 
• o Object 
• p Pointer 


• pal Palette 
• ps Presentation space 
• rcl Rectangle (normally coordinates in an array structure) 
• sb Segment base 
• st Pascal-type string (length of string in first byte) 
• sz C-type null terminated string 
• u Unsigned (always used with the b, I, or s identifiers) 
• v Never use, someone could confuse it with VOID 
• w Word 
• wnd Window 


> A standard qualifier can help someone see the purpose of a 


variable almost instantly. For example, using the Clr qualifier 
tells the viewer that this variable is used in some way with color. 
You can even combine the qualif iers to amplify their effect and 
describe how the variable is used. For example cclrcrs is a 
character variable that determines the color of the cursor on 
the display. Using one to three of these qualifiers usually is 
sufficient to describe the purpose of a variable. The following 
standard qualifiers are examples of the more common types: 
• A;I A{Iray 
• Attr Attribute 
• a Bottom 
• Clr Color 
• Col Column 
• Crs Cursor 
• Dbf Database file 
• F First 
• File File 
• Fld Field 
• L Last/Left 
• Mss Message 
• Name Name 
• R Right 
• Ref Return value 
• Scr Screen 
• Str String 
• T Top 
• X Row 
• Y Column 


> An optional "pointer reference:" 


• 1,2,3 State pointer references as in csavclrl, csavclr2, 


etc. 


• Max Strict upper limit as in nFldMax, maximum number of 


Fields 


• Min Strict lower limit as in nRecMin, minimum number of 


Records 


A note on function names 


In some of the tables throughout this book, long function names have 
been broken and hyphenated. When using these functions, you 
should spell the names solid, without the hyphen. 


EE}EREREEE§REillffiffi 


HIS chapter provides you with three different types of 
application specific information. Each piece of information 


helps you to program more efficiently and with less effort without 
buying a lot of third-party products that your company might not 
want to support. Learning to use the tools supplied with a product 
might seem mundane or unimportant, but these tools can help you 
realize significant gains in programming speed and accuracy. This is 
an important consideration in any production programming 
environment. We're not talking about the obvious tools like the 
compiler and editor that you need to program, but the ancillary tools 
supplied with OS/2 that many programmers ignore as too 
insignificant. 


The first section of the chapter tells you how to automate and 
enhance the OS/2 command-line (character-mode) interface. This 
includes REXX programming and batch files. You can extend the 
REXX character mode interface to the Workplace Shell (WPS) using 
PMREXX. Many programmers already are familiar with DOS-style 
batch files; OS/2 adds a few twists to batch file programming that 
you might find interesting. While many people think that REXX is 
simply another batch file language, it provides much more in the 
hands of an experienced programmer. The Developer Connection for 
OS/2 includes many enhanced REXX programming tools that you 
can use to create fully functional Presentation Manager (PM) 
applications; you do not need the Developer Connection to run these 
applications. Using both tools helps you completely automate your 
programming environment and might even provide an alternative to 
C++ or assembly language programming in some instances. 


1'11 simply refer to The Developer Connection for OS/2 as the 
Developer Connection from this point on. The Developer 
Connection is a subscription service that you can order from IBM to 
keep you informed of the latest OS/2 developments and tools. You 
can order this service by calling 1-800-6-DEVCON. Annual service 
rates start at $200. The subscription currently includes four CD-ROM 
updates per year along with the Deue/oper Connecfjon Netus 
newsletter. 


The second section of this chapter tells you how to manipulate the 
Workplace Shell (WPS) and use the graphical user interface to your 


advantage. This is an important section considering that many 
programmers come from a character-mode background and might not 
feel comfortable with a graphical user interface. Using the graphical 
user interface also means creating test suites using a combination of 
REXX and the WPS (or the PMATE utility supplied with the 
Developer Connection). Make sure you install PMREXX support 
during your OS/2 installation. This allows you to extend REXX to the 
Workplace Shell. In addition, many of the examples will require you 
to use the advanced tools provided with the Developer Connection. 


Finally, we explore the Developer Connection. The Developer 
Connection is a replacement for IBM's Profession Developer Kit 
(PDK) with a few exceptions and a lot of additions. Unlike the PDK, 
the Developer Connection is not a one time service; it is a 
subscription service that keeps you constantly up-to-date on the latest 
OS/2 developments. This is a CD-ROM and newsletter combination 
that contains a plethora of programming tools and other aids. The 
Developer Connection is not simply a compiler (Developer 
Connection provides a compiler only if IBM has one in the beta test 
cycle) or beta testing platform; it contains full documentation for 
many areas of OS/2 that you might find difficult to obtain using other 
methods. In addition, it provides a complete copy of any OS/2 beta 
test components (up to and including the entire operating system) 
and many programming tools that you can use with or without your 
favorite C/C++ compiler. Even if you decide to use a third-party 
compiler, many of the tools in the Developer Connection will help 
you reduce your programming time significantly. (This is especially 
true if you plan to perform any multimedia programming within 
OS/2.) 


Using OS/2 CMD files 
to au+oma+e your work 


The OS/2 CMD file is equivalent to the DOS BAT file; both allow 
you to automate tasks at the command line. Anything that you can do 
with a DOS batch file you can do with an OS/2 CMD file. The two 
environments are so alike that you can run many of your DOS batch 
files under the OS/2 environment with little more change than the 


Table 1 -1 


file extension. This means that you conceivably could move many of 
your DOS batch files into the OS/2 environment with little or no 
change. Of course, you will want to modify the files to take advantage 
of OS/2 features. 


There are a few additional commands provided for the OS/2 batch 
programming environment. While you can emulate many of these 
extra commands in the DOS environment, the OS/2 environment is 
more convenient. The SetLocal and EndLocal commands are one 
example of these enhancements. (There is both a command and 
function version of these commands.) You no longer need to rely on 
esoteric methods for preserving the user's original drive, directory, 
and environment. These commands allow you to save and restore 
these important characteristics using simple one-line commands. 
Table 1-1 provides a complete list of the OS/2 batch file commands. 


The OS/2 CMD command summary 


Command Description 


Call 


CMD 


Command 


Echo 


EndLocal 


Exit 


Extproc 


This command allows you to call another batch file from within the 
current batch file. Use it to nest batch files. The Call command 
essentially allows you to create modularized programs using batch 
files. 


Use this command to create another copy of the OS/2 command 
processor. 
Use this command to create another copy of the DOS command 
processor. 
There are two states associated with this command. You can either 
send the current command to the display using Echo On or remove it 
from the display using Echo Off . Using Echo Off within the CMD file 
allows you to hide the details of a process from the user. 


Use this command to restore the drive, directory, and environment 
variables in effect when you last issued a SetLocal command. 


This command allows you to leave the current command processor 
and return to the previous command processor (if any). You return 
to the WPS if there is no previous command processor in effect. 


You can use this command to define yourown batch pocessor. 
This allows you to use any special commands required to 
accomplish the work you need to do in a batch environment. 
CMD.EXE transfers control to your batch file if the Extproc 
command appears as the first line in the batch file. 


Command Description 


For 


Goto 


Pause 


Protshell 


REM 


SetLocal 


The For command allows you to perform repetitive work within a 
batch file. It works much like any other loop command except that 
the entire structure appears on one line. 


Use this command to transfer control from the current point in the 
batch file to any label within the batch file. It works much like the 
BASIC Goto command. 


The If command allows you to perform conditional processing of a 
particular command. If the specified condition is true, then the 
command gets processed; otherwise, it doesn't. There are three 
conditions you can test for: the existence of a particular file, an 
error level returned by an application, or the equivalence of two 
strings. 


You can use this command to stop batch file processing until the 
user presses a key. This command is handy for displaying 
messages on screen and allowing the user time to read them. 


Use this command to specify the user command-line interface 
program and the OS/2 command processor. OS/2 uses a default 
of CMD.EXE for this command. 


This command allows you to place remarks in your batch files. 


You can use this command to save the current drive, directory, 
and environment variables. This allows you to define a local 
environment without changing the original settings. Use the 
EndLocal command to restore the saved settings. You cannot nest 
SetLocal commands; OS/2 saves only the most recent settings for 
you. 


Use this command to specify the DOS command processor. OS/2 
uses a default of COMMAND.COM. 


This command provides the means for using more than 10 
variables within a batch file (of course, only 10 are visible at any 
time). You can shift only to the left. In other words, parameter 1 
becomes parameter 0. OS/2 does not allow for reverse shifting; 
any parameters that scrolled off the left side of the parameter list 
are unrecoverable. 


As you can see, there are minor differences between the OS/2 and 
DOS environments. This means that you can refer to one of the 
many DOS batch file programming books on the market for 
additional ideas. My personal favorite in this category is Enhcmced 
Botch F!./e Progrommjng (2nd Edition) by Dan Gookin (ISBN 0- 
8306-3854-7). 


Using REXX to create utility 
programs and o+her aids 


Anyone who uses an operating system for very long will find it not 
only convenient, but essential to automate some of the tasks that they 
perform. Rather than mechanically reproduce the same set of 
keystrokes repeatedly, it is a lot faster to record them once and let 
the computer do the repetitive work. 


While OS/2 does provide a batch language, there are two reasons 
that REXX is a much better solution for automating repetitive tasks. 
First, REXX is a lot more powerful than the native batch language. Its 
flexibility will allow you to do a lot more with less effort. In some 
ways, you can think of REXX as the batch enhancers used by many 
DOS users. Second, the REXX file extension of CMD will allow you 
to separate OS/2 specific batch files from DOS batch files on the 
same drive. 


Understanding 
FtEXX command files 


To use REXX, you must end the filename of your batch file with the 
CMD extension and provide a comment as the first line. When you 
type the name of a file with the CMD extension at the OS/2 prompt, 
it looks at the file, determines that it is a REXX batch program, then 
executes the instructions using the REXX interpreter. Every REXX file 
can contain one or more of the following elements: 


> Comments 
> Strings 
> Instructions 
> OS/2 commands 
> Assignments 
> Labels 
> Internal functions 


Each element within a REXX program allows you to perform a 
specific task. The following sections describe these elements in 
further detail. 


Comments 


Comments provide the means for documenting your batch file. 
Documentation consists of your name, the date that you created the 
batch file, the purpose of the batch file, notes on why you added 
some sections to the batch file or performed some specific task, and 
a listing of any modifications that you make to the batch file. Many 
people feel that documenting their batch files is a waste of time and 
effort, only to find out later that they can't figure out why they wrote 
a batch file the way that they did. Comments always take some 
amount of time to write correctly, but the dividends to you later more 
than make up for the expenditure today. 


Strings 


Strings allow you to tell the person using your batch file something or 
ask for a piece of information. You also can use strings to dress up 
the appearance of your program. Any time you want to send text to 
the display, you use a string to do it. 


A string always appears within a set of single or double quotes. For 
example, both "Hello World" and `Hello World' are strings. In most 
cases, the choice of using either a single or double quote is up to 
you. When the REXX interpreter sees the quote, it stops interpreting 
what you've written and simply displays it. 


You occasionally will need to display a quote within a string. If you 
need to display a single quote, then enclose your string with double 
quotes as follows: "Jack liked Mary's new car." Sometimes you'll 
need to display double quotes in conjunction with a single quote. In 
these cases, just use two double quotes together. For example, the 
string "Mary heard Jack's brother say "'Boy, do you have a nice 
car." displays as: Mary heard Jack's brother say "Boy, do you have 
a nice car." 


Instructions 


Instructions are REXX specific commands and control structures. This 
is the way that you tell REXX how you want it to perform a specific 
task. For example, if you want REXX to display something on screen 
you can use the SAY command as follows: SAY ``Something." I cover 
commands and control structures as part of the Macro Language 
description in the following paragraphs. 


OS/2 commands 


Allowing you to execute OS/2 commands is one of the main reasons 
to use REXX. Once you get the information that you need from the 
person using your batch file, tell them what the batch file is going to 
do, and tell REXX how you want it to perform a specific task, you'll 
execute one or more OS/2 commands. I show you how to integrate 
OS/2 commands with the REXX macro language in the programming 
section of this chapter. 


Assignments 


Sometimes, you'll need to keep track of a specific piece of 
information during the execution of the batch file. REXX allows you 
to do this by assigning the piece of information to a variable. The 
variable acts like a box that you store the piece of information in until 
you need it again. Just like any other box, you can take the old piece 
of information out and put a new piece of information in. For 
example, you can store the value of an arithmetic expression in a 
variable as follows: Sum = 1 + 2. The variable Sum now contains a 
value of 3. If you make another assignment later, REXX will replace 
the value of 3 with a new value. You'll see some practical examples of 
using assignments in the programming section of this chapter. 


Labels 


Labels act as street signs in your batch file. If you want REXX to stop 
performing a specific task, you can tell it to go to another part of the 


batch files. Labels provide the means for telling REXX where to go; it 
simply looks for the right street sign. 


Internal functions 


REXX provides you with shortcut methods for performing some tasks. 
Internal functions allow you to take one or more pieces of information 
and use them to find out something else. For example, if you want 
REXX to figure out the maximum of three numbers, you would use the 
MAX function as follows: MAX(Numberl , Number2, Number3). REXX 
provides you with over 50 built-in functions. I discuss some of the more 
important functions as part of the following section. 


Using the F{EXX macro language 


There are three essential parts to any REXX program: control 
structures, commands, and functions. A control structure tells REXX 
how to execute your program. In essence, it is a map that REXX 
follows from the start of your program to the end. A command is an 
instruction that you want REXX to perform. For example, you can 
tell REXX to display some information on screen or retrieve 
information from the keyboard. A function allows you to take a 
shortcut to finding out specific pieces of information. In many ways, 
a function in REXX is just like a function in your spreadsheet. You 
provide REXX with one or more pieces of information, and it 
provides the information you're looking for as output. 


These three parts of REXX combine to form a macro language. In 
many ways, this macro language is no different from the macros that 
you create for your word processor or spreadsheet. The only real 
difference is that REXX works with the operating system, not a 
specific application. 


Boolean operators 


There is one element of the macro language that crosses boundaries 
into just about every area of REXX programming. Boolean operators 


help REXX evaluate a given set of condi.tions and perform a specific 
task based on what it finds. There are only two values returned by 
Boolean operators: 1 for true and 0 for false. 


-*- AND operator (&) The AND operator allows you to perform a 


logical union of two expressions. You are in effect saying, if expression 
1 is true & (and) expression 2 is true, then return a value of true. If 
either expression is false, then the entire expression is false. 


-)i(-Comparisons > < = REXxallowsyouto compare tovalues. 


For example, if you wanted to see if one value was greater than 
another, you would type: Varl > Var2. Likewise, if you wanted to see 
if one value is less than another, you would type: Varl < Var2. The 
output of these comparisons is 1 for true or 0 for false. 


-*- NOT Operator (1 or \) You use the NOT operator to reverse the 


condition of an evaluation. For example, if you said \(i = i ), then 
REXX would evaluate the expression as false, even though 1 does 
indeed equal 1. 


-*-OR Operator (i) The OR operator allows you to perform a 


logical intersection of two expressions. You are saying, if expression 1 is 
true : (or) expression 2 is true, then return a value of true. The only 
time you receive an output of false is when both expressions are false. 


Control structures 


There are three basic forms of control structure supported by REXX. 
The conditional statement allows you to perform an action based on 
whether or not an expression is true or false. There is only one action 
to perform. Think of a conditional statement like a light switch in 
your home. You can either turn the light on or off depending on the 
position of the switch. The IF..THEN..ELSE control structure is the 
conditional statement for REXX. 


REXX also supports a switch statement. In this case, you select one 
atction from a group of actions based on a specific condition. Think of 
a switch statement like the soda machine at work. You insert a coin, 
press one out of a group of switches, and receive a specific kind of 


soda in return. The switch statement in REXX is the 
SELECT. .WHEN. .OTHERWISE control structure. 


The final control structure is the loop statement. A loop statement 
allows you to perform one section of code one or more times based 
on a counter variable. For example, say that you wanted to get three 
candy bars from the machine at work. First, you'd place some money 
in the slot, then you'd pull the appropriate switch and retrieve your 
candy bar. To get three candy bars, you'd perform this sequence of 
steps three times. There are several loop statements for REXX 
including the DO..LOOP, DO UNTIL.., DO WHILE.., and DO 
FOREVER control structures. 


You can "nest" these control structures to perform more elaborate 
sequences of instructions. Nesting structures is the process of placing 
one control structure within another. Each structure still is its own 
unique element, but they work together to produce a specific result. 


-)i(- DO rvumber Stafemenfs [LEAVE] END This form of the 


DO..END loop is the most basic form of the control structure that 
you'll ever use. REXX executes the instructions within the control 
structure the number of times specified by number. The only way to 
exit the structure prematurely is to add a LEAVE clause. The LEAVE 
clause is an optional part of this control structure. The following 
example shows how to use the DO..END loop: 


SAY "Enter a number. " 
PULL Counter 
Lastcount = 1 
DO Counter 


SAY Lastcount 
Lastcount = Lastcount + 1 
SAY "Do you want to count some more?" 
PULL Answer 
IF Answer = "NO" 


THEN LEAVE 


END 


Notice that you must add an END clause to the end of this control 
structure. Otherwise, REXX will not know when the control structure 
ends. This example also shows one way to use the LEAVE clause. 
Notice that unless the user enters NO when asked if they want to 
count some more, that REXX continues to process the loop. 


-`,`.,'`- D0 Valriab]e -- Numberl T0 Number2 Statements T:LEAINE] 


END In some cases, you can increase program execution speed 
and reduce memory requirements by combining a counter variable 
with an output variable. This form of the DO..END loop allows you to 
do both with a little careful planning. It is like the previous form of 
the control structure in all other respects. The following example 
shows you how to use this form of the DO..END loop: 


DO Counter = 1 TO 10 


SAY Counter 


END 


-)i(- DO WHILE ExpressI.on Sfafemen/s [LEAVE] END You won't 


always know how many times to execute a loop. Sometimes, the 
number of executions depends on conditions that you can't control 
when you write the batch file. The DO WHILE..END loop checks an 
expression before it executes the statements within the control 
structure. It continues to execute the instructions while the expression 
is true. As soon as the expression becomes false, the control structure 
exits and REXX continues execution at the statement following the 
END clause. The following example shows how to use the DO 
WHILE..END loop: 


SAY "Enter a filename you want to display. " 
PULL ListFile 
DO WHILE \(ListFile = "') 


type ListFile 
SAY "Enter a filename you want to display. " 
PULL ListFile 


END 


-)i(- DO UNTIL Expressi.on Sfafemenfs [LEAVE] END The DO 


UNTIL..END loop evaluates an expression after it executes a set of 
statements. This assures that a loop will always execute at least once, 
no matter what happens. The DO UNTIL..END loop continues to 
execute a set of instructions until the expression that you specify 
becomes true. The following example shows how to use the DO 
UNTIL..END loop: 


Counter = 1 
DO UNTIL Counter = 1 /* Loop executes at least once. */ 


SAY Counter 


END 
DO UNTIL Counter = 10 


SAY Counter 
Counter = Counter + 1 


Fro 


Si(- DO FOREVER Sfafemenfs LEAVE END. There are few 


reasons to use the DO FOREVER..END loop. This loop continues to 
execute until the user manages to break out of it. As a result, you 
should always include a LEAVE clause as part of the code for this 
control structure. 


-*-[F I;xprfessi.on THEN Sfafemen/ [ELSE Sfafemenf] The 


IF..THEN..ELSE control structure is one of the most common 
structures that you'll need when creating a REXX program. 
Essentially, this control structure says that, if the expression is true, 
REXX will perform the statement appearing after the THEN clause. 
The ELSE clause is optional, which is why it appears in brackets in 
the heading of this section. REXX automatically performs the 
statement appearing after this clause if the expression is false. The 
following example shows how you would use the IF..THEN..ELSE 
control structure: 


IF Varl > 5 


THEN SAY "Input was greater than 5" 
ELSE SAY "Input was less than or equal to 5" 


You can use this control structure with a DO..END control structure if 
you need to perform more than one statement after the THEN or 
ELSE clauses. The following example shows how you would use these 
two structures together: 


SAY "Type your age and press Enter. " 
PULL Age 
IF Age > 18 


THEN 


DO 
SAY "You are over 18. " 
SAY "What would you like to drink?" 
PARSE PULL DrinkName 
SAY "Fixing you a " DrinkName 
END 


ELSE 


DO 
SAY "You are not over 18. " 
SAY "I can't fix you a drink. " 
END 


-)i(-SELECT WHEN I;¥pressi.onJ THEN SfafemenfJ [WHEN 


I;¥pressi.on2 THEN Statement2..®] [OTHERWISE 
Sfatementn] END The SELECT..WHEN..OTHERWISE switch 
is the best control structure to use when there is more thah one 
possible choice that the user could make. REXX looks at 
Express/.on7 first. If this expression is true, then it executes the 
statement following the first THEN clause. If the expression isn't 
true, REXX evaluates the second and following expressions. If 
REXX can't find any true expressions, then it looks for the 
OTHERWISE clause and executes any statements appearing after 
it. Once it executes one of the THEN clause statements, REXX 
exits the control structure. You need to supply only one WHEN 
clause with this control structure. The second and preceding 
WHEN clauses are optional. The OTHERWISE clause is optional as 
well. However, if you don't provide an OTHERWISE clause, REXX 
will exit the control structure without doing anything if it doesn't 
find a true expression. The following example shows how you 
could use the SELECT..WHEN..OTHERWISE switch: 


SAY "Type your age and press Enter. " 
PULL Age 
SELECT 


muEN Age < 13 


THEN SAY "You are a child. " 


WHEN (Age > 12) & (Age < 20) 


THEN SAY "You are a teenager. " 


OTHERWISE 


SAY "You are an adult. " 


END 


Notice that you must always end a SELECT. .WHEN. .OTHERWISE 
control structure with an END clause. This is the only way that REXX 
knows that you finished the switch. Also, notice that the 
OTHERWISE clause does not require a THEN clause. If you add a 
THEN clause, REXX will exit your program with an error. 


Like the IF..THEN..ELSE control structure, REXX allows you to 
combine the SELECT..WHEN..OTHERWISE switch with the 
DO..END control structure. This allows you to follow a THEN clause 
with more than one statement. 


Commands 


Many people have trouble keeping commands and functions separate 
when creating a program. The key to remember is that a function 
always returns a value but might not do any other work. A command 
always performs some type of work but never returns a value. REXX 
offers a wide assortment of commands that help you control the 
batch file environment. 


-)i(- ADDRESS [£nwJ.ronmenf [Express/.on]] [[ I/a/ue] ExpressJ.on J] 


This command allows you to redirect the current input stream (the 
statements in your REXX application) to another application. For 
example, you could direct the stream to an editor or other 
application and perform macro-like functions. 


There are two ways to use this command. The first method is to 
place the name of the application that you want to use along with 
whatever command that you want that application to perform. For 
example, ADDBESS CMD DIB *.* invokes the command processor 
and asks it to get a list of files in the current directory. The input 
stream immediately returns to the REXX application. The second 
method involves using only the application name with the command. 
For example, ADDRESS DOIT redirects the input stream to an 
application called DOIT until you cancel the redirection. Every 
statement in your REXX application gets sent to the new application. 
You cancel the redirection with the next ADDRESS command. Use 
ADDRESS by itself if you want to set the input stream back to the 
REXX application. 


-*- ARC [7eT mp/afe] The ARG command is the same as the PARSE 


UPPER ARG command. You use it to retrieve the argument strings 
sent to a program or internal routine and assign them to variables. 
For example, if your application contains the statement CALL 
MYPF30C ('String 1 I,1 ) and you placed the command AF}G 
STRINGI NUMl at the beginning of the subroutine, then STF3lNGI 
would contain 'String 1 I and NUMl would contain '1 I. 


-)i(- CALL rvame [ExpressJ.on] One of the simplest forms of this 


command is to call a sub function from within a main procedure or 


function. In many cases, it is more convenient to break your program 
into small pieces. Each piece performs a specific part of a more 
complex task. For example, you could create a single routine for error 
trapping or displaying information on screen. The following example 
shows a simple method of using the CALL command: 


/* This is the main procedure. It displays a message to the 


viewer, then requests some information. If the user doesn't 
supply the information, the main procedure calls an error 
handling function to request the information again. */ 


Who="' /* Initialize the variable. */ 
DO WIIILE Who = '''' /* Do until user provides a response. */ 


SAY "Hello! I am REXX" 
SAY "What is your name?" 
PARSE PULL Who 
IF Who = '''' /* Did the user provide a response? */ 


THEN CALL Error /* If not, call error handling function. */ 
ELSE SAY "Hello" Who 


END 
EXIT 


/* This is the error handling function. It displays an error 


message, then returns so the main procedure can ask the user to 
provide the requested information. */ 


Error : 
SAY "Please type your name! " 
RETURN 


There are a few interesting points about this program. First, the error 
routine uses a label for identification. Notice that the function name is 
followed by a colon. Second, the function ends with a RETURN 
command, not the EXIT command. You want to return to the main 
procedure once the user presses the enter key. Using EXIT would 
simply return you to the OS/2 prompt. 


-)i(-CALL <OFF i ON> <ERROR i FAILURE : HAL:I i 


NOTREADY > I NAME 7raTprvame] This version of the CALL 
command works much like the version discussed in the previous 
section. The big difference is that you use this version for error- 
trapping routines. The ON keyword tells REXX to call a specific 
procedure should a given event occur (ERROR, FAILURE, HALT, or 
NOTREADY). The optional NAME keyword tells REXX what 
subroutine to call when the event occurs. You can use the OFF 
keyword to turn off error trapping for a specific event. 


-)i(- DROP [Varl.ab/ervame] Use this command to unassign one or 


more variables. You separate each variable with a space or comma. 
The DROP command allows you to assign a list of variables to one 
variable. Calling DROP with the variable enclosed in parenthesis 
unassigns all the variables in the list without unassigning the variable 
that holds the list. 


St(- EXIT [Express/.on] Allows you to exit from the current program 


back to the calling program. In most cases, the calling program is the 
OS/2 command processor. The optional expression variable allows 
you to return a string to the calling procedure or application. 


-*- INTERPRET Express/.on REXX allows you to build a command 


within a string using concatenation or any other legal means. You 
can execute the command using the INTERPRET command. For 
example, if you had a statement that contained SOMESTB = 
`ADDF3ESS CMD DIR *." and added the statement lNTEF3PRET 


SOMESTB, then you would see a list of files in the current directory. 


-*- ITERATE [l/a".ab/ervame] This command allows you to 


increment the value of a variable. If you do not include a variable 
name, then it increments the value of the variable used to call the 
command. For example, the statement lF I = 2 THEN ITEBATE 
would result in an increase in the value of I. This command normally 
appears within loops and provides a means for altering program 
flow. 


-)i(- NOP The NOP command stands for no operation. Use this 


command when you don't want to do anything at all. For example, if 
you use a SWITCH control structure to select from a set of 
conditions, one condition could be to do nothing. 


-)i(- NUMERIC DIGITS [E;xpressi.on] or NUMERIC FORM 


< SCIENTIFIC : ENGINEERING : [VALUE] Expressi.on> 
or NUMERIC FUZZ [EJxpress/.on] Use this command to 
format numeric data and to determine the accuracy of numeric 
manipulations. There are three forms of this command. The DIGITS 
keyword allows you to define the number of digits of accuracy used 
for calculations. Each additional digit increases accuracy but reduces 
application speed and increases memory requirements. You need to 


determine a reasonable level between accuracy and efficiency for 
each application that you create. In most cases, the default level of 9 
digits provides sufficient accuracy. 


The FORM keyword allows you to define how REXX displays numeric 
data using exponential notation. The SCIENTIFIC and ENGINEERING 
keywords are self explanatory. The VALUE keyword allows you to 
supply an expression that must evaluate to either scientific or 
engineering. The default setting for this command is scientific. 


The FUZZ keyword allows you to specify how many digits are ignored 
when you perform a comparison between two numbers. For example, if 
you set the fuzz factor to 1 and compared 101 with 100, REXX would 
consider them equal. This allows you to perform comparisons between 
numbers that might vary slightly from one another due to rounding 
errors. The FUZZ setting defaults to 0. You must specify a whole 
number that is less than the number specified in the DIGITS setting. 


-*- OPTIONS EJxpress4.on The OPTIONS command allows you to 


pass directives to the language processor. There are four keywords 
recognized by the language processor: ETMODE, NOETMODE, 
EXMODE, and NOEXMODE. The ETMODE keyword turns on 
support for the double-byte character set (DBCS). This provides 
support for foreign languages in your application. Using the 
NOETMODE keyword turns this support off . The EXMODE keyword 
tells the language processor to handle DBCS data in a logical manner 
when it appears in instructions, operators, and functions. The 
NOEXMODE keyword turns off this support. 


-)i(-PARSE [UPPER] <ARG i PULL i SOURCE i VALUE 


[EjKpressi.om] WITH i VAR rvame i VERSION > Temp/afe£I.sf 
The PARSE command looks complex but performs fairly routine tasks. 
The UPPER keyword converts all input to uppercase. In addition, there 
are six different functions that you can perform with the PULL 
command. The ARG keyword is discussed under the ARG command. 


The PARSE PULL command accepts input from the keyboard until 
the user presses Enter. It places the input into the specified variable. 
PARSE PULL allows you to enter characters in either upper- or 
lower case, there is no loss of formatting. 


Use the SOURCE keyword to determine the source of the program 
that you are running. The string always begins with OS/2 followed by 
one of the keywords COMMAND, FUNCTION or SUBROUTINE. 
The program name, complete with path, is the last part of the string. 


The VALUE keyword allows you to parse the result of a function and 
format it for output. The first part of the expression contains the 
name of a REXX function. You follow this with the WITH keyword. 
Finally, you supply a set of variables and strings that PARSE uses to 
format the output. For example, you could add the statement PABSE 
VALUE TIME() WITH Hours I:I Minutes I:I Seconds to your program. 
Hours, Minutes, and Seconds are three variables that contain the 
output of the TIME() function. The colon separating the variables 
would appear as part of the output. 


The PARSE VAR command allows you to perform complex variable 
manipulations. You specify the name of a variable that you want to 
parse and follow it with the name of a variable to receive the parsed 
data. The contents of the original variable do not change unless you 
specify it as the third variable in the command. For example, if you used 
the statement PABSE VAB Somestr Firstword Somestr, then Somestr 
would contain everything but the first word and Firstword would contain 
only the first word of a string when the statement executed. 


Use the VERSION keyword to determine the version of the REXX 
interpreter. It returns a string containing the word REXXSAA, 
followed by the version number and the release date. 


-*- PULL Vat/.ab/e The PULL command acts much like the PARSE 


PULL command. It places a value typed at the keyboard into a 
variable. Unlike the PARSE PULL command, PULL converts all 
characters to uppercase. This is a good feature to use when you want 
to use the keyboard input as part of an expression for a control 
structure. 


-*- PUSH [£xpress/.on] The PUSH command works essentially the 


same as it does in other languages. In this case, you push the 
contents of an expression onto a LIFO queue. If you don't provide an 
expression, the queue contains a blank line. Every PUSH command 
adds one line to the queue. You use the QUEUED command to 
determine the number of strings that the queue contains. 


-* QUEUE [Express/.on] The QUEUE command works essentially 


the same as it does in other languages. In this case, you push the 
contents of an expression onto a FIFO queue. If you don't provide an 
expression, the queue contains a blank line. Every QUEUE command 
adds one line to the queue. You use the QUEUED command to 
determine the number of strings that the queue contains. 


-)i(- RETURN [ExpressJ.on] Allows you to return from the current 


procedure to the calling procedure. This is the command that you use 
to return from a sub function to the function that called it. You also 
could use this command at the end of the program, but the EXIT 
command allows you to quickly recognize the program ending point. 
You optionally can add a string to the RETURN command. REXX 
passes the string to the calling procedure. 


-)i(- SAY ExpressJ.on The SAY command allows you to output the 


contents of an expression to the display. The expression can contain 
variables, math expressions, or strings. 


-*- SIGNAL [habe/rvame : VALUE I;xpressi.on i OFF [ERROR i 


FAILURE i HALT i NOVALUE i SYNTAX i NOTREADY] : 
ON [ERROR i FAILURE i HAFT i NOVALUE i SYNTAX : 
NOTREADY] [NAME 7raTprvame]] The Signal command 
provides a means for changing the program flow. There are four 
different ways to use this command. The first method uses the value 
contained in Labs/Ivame to go to a specific label within the program. 
This acts much like a jump command in other languages. The second 
method works much like the first. The VALUE option allows you to 
change program flow based on an expression. You do not need to 
include the word VALUE on the command line to make this option 
work properly, but it does improve readability. 


The ON and OFF keywords work hand-in-hand to allow you to trap 
specific conditions. The OFF keyword turns off trapping for the 
specified condition, while the ON turns it on. The optional NAME 
parameter of the ON keyword allows you to set a destination for error 
trapping. If you do not specify the NAME parameter and a label name 
in the rraplvame variable, then the ON keyword acts much like the 
OFF keyword-it turns off error trapping for the specific event. 


-`i`.,'`-TRAICE |Number \i String \i Symbol 'i VAILHE Expression 


[ALL i COMMANDS i ERROR i FAILURE i 
INTERMEDIATES : LABELS : NORMAL i OFF : RESULTS 
i ? ]] Use this command to debug your REXX applications. It 
allows you to keep constant watch over specific variables, 
expressions, and events. There are several ways to use this 
command. The IVumber variable contains a whole number. This 
option works only when an interactive debug is active. Using a 
positive number forces REXX to skip that number of clauses in the 
current application. A negative number not only forces REXX to skip 
the clauses, but inhibits all debugging as well. 


The Sir/.r7g or Express/.on variable contains a numeric option, 
alphabetic option, or a null value. The Symbo/ option contains the 
same information except that it contains a constant value. The 
numeric options are the same as the IVumer/'c variable description. 
The alphabetic options refer to one of the following options 
described in the following paragraphs: ALL, COMMANDS, ERROR, 
FAILURE, INTERMEDIATES, LABELS, NORMAL, OFF, and 
RESULTS. The null value doesn't do anything with the current trace. 


The ALL option tells REXX to trace all clauses in the application. 
The COMMANDS options traces only clauses containing commands. 
It also displays any return codes. Use the ERROR option if you need 
to trace only error conditions. This option takes effect only after the 
error occurs. The FAILURE and NORMAL options allow you to trace 
all host commands after a failure occurs. Use the INTERMEDIATES 
option to trace all clauses before REXX executes them. It also 
provides the intermediate results of all expressions and substituted 
names. The LABELS option allows you to trace on the labels within 
an application. This works much like the call stack option of many 
debuggers. It is especially useful for tracking the path taken by the 
application to obtain a particular result. The OFF option turns off all 
tracing. The RESULTS option traces all clauses before and after 
execution by REXX. This allows you to see both the input and output 
of a clause. It also displays the values assigned to all PULL, PARSE, 
and ARG instructions. 


The prefix option (?) allows you to reverse the trace conditions. You 
can use it with any of the letter options. For example, if you set 


interactive trace on, then use a prefix option, REXX turns interactive 
trace off . This option is convenient when you need to switch between 
two trace states in an application and don't want to repeat a complex 
set of instructions each time. 


Functions 


Functions always return a value. As a result, you normally set a 
variable equal to the value of the function. For example, if you 
wanted to find out the absolute value of a number, you could use the 
ABS function as follows: Absval = ABS(SomeNumber). Notice that 
there is no space between the left parenthesis and the function name. 
As an alternative to sending the output of a function to a variable, 
you can send it directly to the display using the SAY command. 


-)i(- ABBREV(S/ring, Vari.ab/e I, £ength]) Use this function to check 


whether the contents of War/.ab/e match the starting characters 
contained in Sir/.ng. For example, if War/'ab/e contained "Some" and 
Sir/.r7g contained "Something'', the REXX would return a 1 to signify 
success. REXX returns a 0 for unsuccessful attempts. Lengfh contains 
a number that specifies how many letters must match. For example, if 
War/'ab/e contained "Somt", String contained "Something", and 
Ler}gfh contained 3, then REXX would return a 1 to signify that they 
matched, even though the fourth letters do not match. If the value in 
Ler7gfh exceeds the number of letters in War/.ab/e, then this function 
fails every time. Likewise, if Ler7gfh contains a 0 and Var/.ab/e 
contains a null string, then the function always succeeds. 


-)i(- ABS(rvumbe/) Returns the absolute value of a number. 


Essentially, this makes negative numbers positive. Positive numbers 
remain unchanged. 


-)i(- ADDRESS() Returns the name of the current environment. This 


is the place where all commands in the current file get processed. 
The default environment is CMD. 


-)i(- ARGflrvumber I, Opfl.on]]) The ARG function returns the 


number of arguments passed to a procedure if you call it by itself . If 
you add a value to IVL/mber, then the function returns the value of 


that argument. Specifying a nonexistent argument returns a null 
string. There are two options that you can specify in the Opf/'or7 
parameter. E (for exists) returns a i if the argument exists. For 
example, if the user called the function with three parameters and the 
second parameter was blank, then the exists option would return a 0. 
Likewise, if you checked for the existence of a nonexistent parameter 
(say, parameter 4 when the user supplied only three), the REXX 
returns a 0. 0 (for omitted) returns a 1 if the argument does not 
exist. 


-)i(- BEEP(FJlequeney, Ddra/7.on) This function allows you to send a 


specific frequency to the speaker for a specified time. The frequency 
entry contains the frequency in Hertz. The duration entry determines 
how long you will hear the tone in milliseconds. For example, 
BEEP(1000, 250) sends a 1000 Hz signal to the speaker for a 
quarter of a second. The following example shows how you could 
enhance the error trapping routine of a previous example using the 
BEEP function: 


/* This is the error handling function. It displays an error 


message, then returns so the main procedure can ask the user to 
provide the requested information. */ 


Error : 
BEEP ( 1000 , 250 ) 
SAY "Please type your name! " 
RETURN 


Si(- 82X(String) Use this function to convert a binary string to a 


hexadecimal string. The string must include either ones or zeros. You 
can include spaces at four-digit intervals to aid in readability; do not 
include leading or trailing spaces. 


-)i(- BITAND(Sfrt.ngJ I, [Sfr+.ng2] I, Padcharacfer]]) The BITAND 


function compares two strings bit-by-bit using a logical AND. If you 
do not supply Sir/'ng2, then BITAND uses either a null string or the 
pad character (when supplied) for comparison. Normally, BITAND 
compares sir/.ng 7 and Sir/.ng2, then returns a string with a length of 
the longer string. It simply appends the characters of the longer 
string to the result if you don't supply a pad character. Otherwise, it 
uses the pad character for any comparisons when it runs out of 
characters from either of the two initial strings. 


-*- BITOR(SfringJ I, [Sfring2] I, PadcHaracfer]]) The BITOR 


function compares two strings bit-by-bit using a logical OR. If you do 
not supply Sir/.r792, then BITOR uses either a null string or the pad 
character (when supplied) for comparison. Normally, BITOR 
compares Sir/.ng7 and Sir/.r792, then returns a string with a length of 
the longer string. It simply appends the characters of the longer string 
to the result if you don't supply a pad character. Otherwise, it uses 
the pad character for any comparisons when it runs out of characters 
from either of the two initial strings. 


-)i(- BITXOR(SfringJ I, [Sfring2] I, Padcharacfer]]) The BITXOR 


function compares two strings bit-by-bit using a logical exclusive OR. 
If you do not supply Sir/.r792, then BITXOR uses either a null string or 
the pad character (when supplied) for comparison. Normally, BITXOR 
compares Sir/'r797 and Sir/'ng2, then returns a string with a length of 
the longer string. It simply appends the characters of the longer string 
to the result if you don't supply a pad character. Otherwise, it uses 
the pad character for any comparisons when it runs out of characters 
from either of the two initial strings. 


-*- C2D(String I, rvumber]) This function converts a character 


string to a decimal number. Sir/'ng contains the value you want to 
convert. If you add an X suffix, then REXX treats the string as a 
hexadecimal number. Otherwise, it treats the string as an ASCII value. 
Number determines the number of characters in string used for the 
conversion . 


-)i(- C2X(String) Use this function to convert a string to its 


hexadecimal representation. If you input an ASCII character string, 
then each character is converted individually. Adding an X to the end 
of the string forces REXX to treat the string as a hexadecimal 
number. The function converts the hexadecimal string representation 
to a true hexadecimal number. 


-)i(- CENTER(String, length, [Pad]) This function returns a string 


of Ler7gfh with sir/.r}g centered within it. You can use the CENTER 
function to dress up your displays. The standard padding character 
(the character used to center the string) is a blank. However, you can 
specify any ASCII character using the optional Pad entry. The 
following example shows how you would use the CENTER function: 


Answer = 0 
DO WIIILE \ (Answer=3) 


SAY CENTER("This is my menu",80) /* Center heading on screen */ 
SAY 
SAY "1. Do Something" 
SAY "2. Do Something Else" 
SAY "3. Quit" 
SAY "Enter your selection" 
PULL Zinswer 
SELECT 


WIIEN Answer = 1 


THEN SAY "Did Something" 


WIIEN Answer = 2 


THEN SAY "Did Something Else" 


OTHERWISE 


SAY "Good-bye" 


FRE 


Fro 


-*- CHARIN(rvame I, [Sfarf] I, £ength]]) You can use CHARIN to 


input characters from any source. Ivame contains the name of the 
input source. The default input source is the keyboard (STDIN). The 
function allows you to specify a starting point for persistent input 
sources such as files. This allows you to start reading from a point 
other than the beginning of the file or other persistent source. The 
default setting is to read from position zero. You also can specify the 
length of the input stream by proving a value for Ler7gfh. 


-)i(- CHAROUT(rvame I, [Sfring] I, S/art]]) Yoin can use 


CHAROUT to output characters to any output. Ivame contains the 
name of the output; siring contains the value that you want to output. 
The default output is the display (STDOUT). The function allows you to 
specify a starting point for persistent outputs such as files. This allows 
you to start writing to a point other than the beginning of the file or 
other persistent source. The default setting is to write starting at 
position zero. This function always returns 0 for a successful write; 
otherwise, it returns the number of characters that it couldn't write. 


-*- CHARSGrvame]) This function returns the number of characters 


left in the input stream. It works with input streams like files, but not 
STDIN (the keyboard) or other indeterminate devices. 


-`,# COMPARE(Stringl , String2 |, PadcharacterTn The 


COMPARE function compares Sir/'ng 7 with Sir/.r792. If the strings are 


identical, it returns 0. Otherwise, it returns the position of the first 
nonmatching character in Sir/'r797. You can use the pad character 
to represent repeating characters at the end of a string if Sir/'ng7 is 
longer than Sir/'r792. REXX uses a blank as the default pad 
character. 


-*- CONDITIONGOpfl.on]) Using this function by itself (which is 


the same as using the Instruction option) returns the instruction 
that REXX executed prior to the currently trapped condition. There 
are two instructions that cause trap conditions: Call and Signal. If 
there is no trap condition, the function returns a null string. There 
are three other pieces of error trapping information that you can 
check using the function. Condition Name returns the name of the 
currently trapped condition. Description returns a string that 
describes the currently trapped condition. If the condition does not 
provide a descriptive string, then the function returns a null string. 
Status returns the status of the currently trapped conditions. There 
are three status conditions. On means that the trapped condition is 
enabled. Likewise, Off means that the trapped condition is 
disabled. Delayed means that the future occurrences of the 
condition are delayed. If there is no trapped condition, REXX 
returns a null string. 


-)i(- COPIES(String, rvumber) This function returns zero or more 


copies of the string that you specify in Sir/.r7g. IVL/mber determines 
the number of copies. 


-*- DATATYPE(Varl.ab/e) This function returns one of two values: 


CHAR or NUM depending on the data type of the variable that you 
supply. You can use this function to check user input for the right 
data type prior to processing it. This reduces the chance that your 
application will stop executing due to faulty user input. 


-)i(- DATEflopfr.on]) This function returns the current date. It 


normally displays the date in a DD MMM yyyyformat. However, you 
can specify an option to change the format. Table 1-2 shows the 
formats available. 


The REXX Date( ) function formats 
Table 1 -2 


Format Description 


8 Base Date-Returns the number of days since o1/01/0001. 


D Days-Returns the number of days, including the current day, since 


the beginning of the year. 


E European Formatted Date-Returns the short form of the European 


formatted date. 


L Long Date-Returns the date in long format. This includes the full 


month name and four digit year. 


M Month-Returns the current month in long form. 


N Normal-Returns the date in normal format. You can accomplish the 


same thing by leaving the option blank. 


0 Ordered Form-Returns the date in a format suitable for sorting. It 


uses the YY/MM/DD format. 


S Sorted Form-Returns the date in a format suitable for sorting. It uses 


the YYYYMMDD format. 


U USA Format-Returns the date in the format used by the united 


States: MMODAV. 


W Weekday-Returns the day of the week in long form. 


-*- DELSTFt]NG(S/r/.ng, C»aracfers I, £ength]) This function 


returns a substring of Sir/.r)g. It starts deleting characters from the 
end of the Sir/.ng starting at position Characters. If you specify a 
length, the function stops deleting characters when it deletes the 
number specified by Ler}gfh. Otherwise, it deletes to the end of the 
string. If Characfers is larger than the length of the string, REXX 
returns the string unchanged. 


-)i(-DELWORD(S/rl.ng, M/art/ I, £ength]) This function returns a 


substring of Sir/'ng. It starts deleting words from the end of the Sir/'ng 
starting at position Worc/. If you specify a length, the function stops 
deleting words when it deletes the number specified by Length. 
Otherwise, it deletes to the end of the string. If Worc/ is larger than 
the length of the string, REXX returns the string unchanged. 


-*-DIGITS() Returns the current numeric digits setting. 


-*- D2C(rvumber I, Pos/ti.ons]) The D2C function converts a 


decimal number to its ASCII equivalent. For example, decimal number 
67 converts to ASCII character C. Pos/I/'or7s allows you to define the 
number of digits in the final result. IVL/mber must contain a positive 
number unless you supply a value for Pos/I/.or7S. It must always 
contain a whole number. 


-)i(- D2X(rvumber I, Pos/ti.ons]) The D2X function converts a 


decimal number to a string containing its hexadecimal equivalent. 
Pos/I/'or7s allows you to define the number of digits in the final result. 
If you specify a longer result than the decimal number holds, then 
REXX pads the result with leading Os for a positive result or Fs for a 
negative result. IVL/mber must contain a positive number unless you 
supply a value for Pos/I/.ons. It must always contain a whole number. 


-*- DIRECTORYflrvewDI+ecfor!/I) When used by itself , this function 


returns the current directory. You can supply an optional value in 
IvewD/`recfory that changes the current directory to the new 
directory, then returns the value of the original directory to the caller. 


-*-ERRORTEXT(IVumber) Returns the error text associated with 


the specified error number. 


-*- F[LESPEC(Op/7.on, I/./espec/./J.ca/7.or)) This function returns the 


requested element of a file specification. Opt/.on contains the element 
that you want returned: drive, path, or name. F/'/espec/'f/'caf/'on 
contains a string with the file specification you want to parse. 


-)i(-FORM() Returns the current setting of numeric form. 


-*- FORMAIT(rvumber I, [Before] I, [Affer] I, [EjKponentp/aces] I, 


Exponenf7rTJ.gger]]]]) This function returns a formatted string. 
IVumber contains the number that you want to format. If you don't 
specify a Before and A#er value, REXX uses the default setup. It 
always rounds a number that contains too many digits for the set of 
formatting rules. Befo/e contains the number of digits before the 
decimal point. After contains the number of digits after the decimal 
point. Expor7er)fp/aces contains the number of digits in the 
exponent. This setting takes effect only when IVL/mber exceeds the 
vahae .Ln ExponentTrigger. 


-*-FUZZ() Returns the current setting of numeric fuzz. 


-)i(- INSERT(Sfr+.ng, Target I, [Positi.on] I,[£ength] I, Pad]]]) The 


INSERT function places Sir/.r7g within Targef. This allows you to 
combine two strings. Pos/i/'or7 tells REXX where to place Sfr/'r7g 
within Target. Lengfh tells REXX how long to make Sir/'ng before 
making the insertion. REXX normally uses spaces as a pad character, 
but you can specify any other character using Pac/. 


-)i(- LASTPOS(S/ringJ, Sfr+.ng2 I, Sfarf]) This function returns the 


last position of Sfr/'r797 within Sir/'ng2. For example, if Sir/'ng7 
contained a space and sir/'r792 contained a variety of characters 
including two spaces, then LASTPOS would return the second 
occurrence of the space. You can override this default setting by 
supplying a value for Sfarf. REXX uses this value as the last character 
it looks at, then searches backward to the beginning of Sir/'r792. 


-*- LEFT(String, Length I, Pad]) The LEFT function returns the left 


part of Sir/.r7g. Ler)gfh contains the length of the result. If Sir/'ng is 
shorter than Length, the REXX pads the right side of the string to 
make it long enough. Normally, it uses a space to pad the string as 
necessary. You can override this default by providing a value for Pacy. 


-)i(-LENGTH(String) Returns the length of sir/'ng. 


-*- L]NE[N«rvame] I, [£i.ne] I, Corn/]]) When used by itself , 


LINEIN returns one line of characters from the keyboard (STDIN). 
Ivame contains the name of another input stream if you don't want 
to use the keyboard. If this source is a persistent input like a file, 
then you can provide a value for i/`ne. This value tells REXX what 
line of the file you want to start reading. Col/nf contains the number 
of lines that you want to read from the input stream. 


-*- LINEOUT«rvame] I, [S/rT.r]g] I, £i.ne]]) When used by itself , 


LINEOUT sends a carriage return/line feed combination to the 
console (STDOUT). Ivame contains the name of an output device. If 
this is a persistent output device like a file, you can provide a value 
for i/'r7e. This tells REXX what line you want to start writing at. 
Sir/.r7g contains the data that you want to output. If you do not 
provide a value for Sir/'ng, then REXX assumes a null value and 


writes only the carriage return/line feed to the output stream. 
LINEOUT returns 0 if the write is successful or 1 if not. 


-)i(- LINEsflrvame]) Returns i if there are any more lines of data to 


read from the input stream or 0 if none exists. 


-)i(- MAX(rvumber I, rvumber...I) Returns the maximum number in a 


list of numbers. 


-*- M[N(rvdmber I, rvdmbe/...I) Returns the minimum number in a 


list of numbers. 


-*- OVEF{LAY(S/r/.ng, 7a+ge/ I, [Pos/t7.on] I, [£ength] I, Pad]] I) 


The OVERLAY function places Sfr/.r}g over Target. This allows you to 
combine two strings by overwriting the data in one with the data in 
the other. Pos/I/.or7 tells REXX where to place Sir/'r}g within Target. 
Ler}gfh tells REXX how long to make Sir/.r7g before overwriting 
Target. REXX normally uses spaces as a pad character, but you can 
specify any other character using Pac/. 


-)i(- POS(S/r/.ng7, S/ri.ng2 I, Sfarf]) This function returns the first 


position of Sir/'ng7 within Sir/.r792. For example, if Sir/'r797 contained 
a space and Sir/.r792 contained a variety of characters including two 
spaces, then POS would return the first occurrence of the space. You 
can override this default setting by supplying a value for Sfarf. REXX 
uses this value as the first character it looks at, then searches forward 
to the end of Sir/'r}g2. 


-)i(- QUEUED() Returns the number of lines remaining in the current 


queue. 


3t(- F{ANDOM«rvumber7] I, [rvdmber2] I, Seed]]) Returns a 


pseudo-random number. When used by itself , RANDOM returns a 
number between 0 and 999 as a default. You can specify a maximum 
number in IVL/mber7. If you want to specify both a maximum and 
minimum number, place the maximum number in IVL/mber7 and the 
minimum in IVL/mber2. IVumber7 must contain a number larger than 
IVL/mber2. You can vary the output of RANDOM by providing a value 
for Seed. RANDOM always returns a whole number. 


-)i(-REVERSE(Sfn.ng) REVERSE reverses the order of the characters 


ln String. 


-*- RIGHT(String, Length I, Pad]) The RIGHT function returns the 


right part of Sir/'r7g. Ler}gth contains the length of the result. If Sir/.r}g is 
shorter than Ler}gth, the REXX pads the left side of the string to make 
it long enough. Normally, it uses a space to pad the string as necessary. 
You can override this default by providing a value for Pac/. 


-)i(- RXFUNCADD(rvame, Modu/e, Priocedure) Use this function 


to register a new function with REXX. Ivame contains the name that 
you want to assign to the new function. Modu/e contains the name 
of the module that holds the function you want to register. 
Procec/ure contains the name of the function as it appears within the 
native module. The function returns 0 for successful completion. 


-)i(-RXFUNCDROP(rvame) Use this function to deregister a 


function that you previously registered using the RXFUNCADD 
function. Ivame contains the name of the module that you want to 
deregister. The function returns 0 for successful completion. 


-*-RXFUNCQUERY(rvame) The RXFUNCQUERY function checks 


the list of available functions for a specific function. Ivame contains 
the function that you want to check. It returns a 0 if the function is 
registered or 1 if it is not. 


-*- RXQUEUE(GET : SET rvewoueuervame i CREATE I, 


Oueuervame] i DELETE Oueuervame) You can use this 
function to manage REXX queues. It provides four different 
management tools. GET returns the name of the queue that REXX is 
using. SET also returns the name of the queue that REXX is using. 
You set the name of the new queue by providing its name in 
NewQueuevalue. 


The DELETE option allows you to destroy an old queue. You supply 
the name of the queue you want to destroy in OueL/elvame. The 
function returns 0 for a successful deletion. There are five error 
values that the function can return: 5 (not a valid queue name), 9 
(queue does not exist), 10 (queue is busy), 12 (memory failure), and 
1000 (initialization error, check the OS/2.INI file). 


The CBEATE option allows you to create a new queue. You can 
supply a name in Oueuelvame. If you don't supply a name, then 
REXX creates a name for you. In either case, the function returns the 
name of the newly created queue. 


-*-SIGN(rvumbe/) Returns the sign of number. 


-)i(-SOURCELINEflrvumbe/I) Returns the number of lines in the 


current source file when used by itself . If you supply a number for 
IVumber, then SOURCELINE returns that line from the source file. 


-*- SPACE(S/rT.ng I, [rvdmber] I, Pad]]) Use this function with 


strings to remove or add spaces. Sir/'r7g contains the string you want to 
format. IVumber contains the number of spaces that you want between 
each word in Sir/'r)g. If you specify a value of 0, then REXX removes all 
spaces from the string. It always removes leading and trailing spaces. 
You can specify another fill character by providing a value for Pac/. 


-*- STF{EAM(rvame I, [C, Sfreamcommand] : [D] i [S]]) This 


function returns a string that describes the success or failure of an 
operation on a character stream. Ivame contains the name of the 
character stream. C (command) performs the command specified in 
Sfreamcommar7c/ on the character stream. D returns a description of 
the character stream status. The standard statement is followed by a 
colon and (if appropriate) an extended error number. S is the default 
setting for this function. It returns the state of the character stream. 
There are four values returns by Stream as follows. 


> Error-The character stream experienced some type of error. This 


includes any input, output, or other character stream errors. You 
usually can get a more detailed description using the D option. 


> Beady-The character stream is ready for use. You can 


perform any operation, including input and output. This does 
not guarantee that the operation will succeed. 


> NotBeady-The character stream is not ready for use. Any 


attempt at using it probably will result in failure. 


> Unknown-The state of the stream is not known. This usually 


means that you failed to open a file before checking its state. It 
could mean that the file or other stream does not exist. 


-*- STRIP(String I, [Opfi.on] I, Characfer]]) The STRIP function 


allows you to remove characters from string. The default character is 
a blank. Opt/.or7 contains a removal option: leading, trailing, or both. 
The default option is to remove both leading and trailing character. 
You can specify a different character for this function by adding a 
single character value to Characfer. 


-`1`.,'`- SUBSTR(String, Firstcharacter, Length| You can use this 


function to obtain a part of a string. The Sir/.r7g variable contains the 
original string. F/'rsfcharacfer contains the number of the first 
character that you want in the resultant string. Ler7gfh contains the 
length of the resultant string. 


-)i(-SUBWORD(String, Positi.on I,£ength]) The SUBWORD 


function returns a substring of Sir/'ng starting at Pos/I/.or7. The 
function uses a default of the remainder of the string. You can modify 
this behavior by specifying Ler7gfh. In this case, SUBWORD returns 
only the number of words that you specify. This function always 
removes leading and training blanks. If you specify a starting position 
larger than the number of words in the sentence, SUBWORD returns 
a null string. 


-*- SYMBOL(Symboo Returns the current state of Symbo/. There 


are three different conditions. REXX returns Bad if the symbol does 
not exist. It returns Var if the symbol is a variable. Lit represents a 
literal symbol, which is a constant or variable with an unassigned 
value. 


-)i(-SYSCLS This function clears the display. 


3i(- SYSCREATEOBJECT(C/assrvame, Tit/e, £ocafi.on I, Sefup]) 


The SYSCREATEOBJECT function allows you to create a new 
object. C/asslvarr)e contains the name of the object class that you 
want to create I/i/e contains the title for the object. Locaf/'on is a 
description of where REXX can find the object class definition. You 
can use either a descriptive or file system path. The SefL/p parameter 
allows you to pass information to the object class in the form of a 
string. The function returns 1 if successful or 0 if unsuccessful. 


-*- SYSCURPOS flRow, Cofl) There are two ways to use this 


function. If you call it without any parameters, then REXX returns the 
current cursor position without changing it. Adding parameters moves 
the cursor but still returns the previous cursor position. The cursor 
row and column start in the upper left corner at coordinates 0, 0. 


Si(- SYSCURSTATE (ON i OFF) Use this function to set the state of 


the cursor (either on or off). 


-)i(-SYSDEREGISTEROBJECTCLASS(C/assrvame) This function 


allows you to deregister a class registered with the 
SYSREGISTEROBJECTCLASS function. C/assIvame contains the 
name of the object class that you want to deregister. The function 
returns 1 if successful or 0 if unsuccessful. 


-*-SYSDRIVEINFO(Dr/.ve) The sYSDRIVEINFo function returns 


the drive letter, free space, total space, and volume label in a string. 
You must provide a drive letter as input. The function returns an 
empty string if the drive doesn't exist or isn't available. 


-*- SYSDRIVEMAP flDrl.ue], [Opfl.ons]) This function reports the 


drives available to the system. It uses a default of a beginning drive of 
C and all accessible drives, whether local or remote. The string 
returned by this function contains a list of drive letters followed by 
colons and separated by spaces. You can specify a different starting 
drive using the Dr/.ve parameter. There also are several search 
options that you can use as listed here: 


> Used-This is the default option. It returns every drive that the 


system can access whether in use or not. It includes both local 
and remote drives. 


> Free-This option reports both local and remote drives that are 


not in use. In other words, you can access these drives 
immediately. 


> Local-Use this option if you want a listing of local drives 


whether they are in use or not. 


> Bemote-The Bemote option provides a list of remote drives. It 


does not matter if the drives are currently in use by someone else. 


> Detached-Use the Detached option when you need a list of 


detached network resources. In other words, the user could 
normally access the drive but current cannot for some reason. 


-)i(- SYSDROPFUNCS Always use this function with care. It drops all 


the loaded REXxutil functions from memory. This is a great way to 
free up memory for applications. Unfortunately, it also means that 
the REXxutil functions are unavailable to any OS/2 session 
(essentially making REXX unavailable for use). 


-)i(-SYSFILEDELETE (I/./e) The SYSFILEDELETE function allows 


you to remove a file from disk. It does not support wildcard 
characters; you must supply a specific filename. The function returns 
the following codes: 


0 File Deleted successfully 
2 File NotFound 
3 Path Not Found 
5 Access Denied 


26 NotDOSDisk 
32 Sharing violation 
36 Sharing Buffer Exceeded 
87 Invalid parameter 


206 Filename Exceeds Range Error 


-*- SYSFILESEAFtcH (S/r/.ng, I/./enaJr)e, I/a/1.ab/e, lop/7.ons]) 


The SYSFILESEARCH function allows you to find a string within a 
file. Sir/.ng contains the string that you want to search for. F/./er7ame 
contains the name of the file that you want to search. War/.ab/e 
contains the results of the search. This is an array containing one 
entry for each string, containing the search value. Element 0 of this 
array contains the total number of entries in the array. 


There are two options that you can use with this function. The C 
option forces a case-sensitive search. The default setup uses a case- 
insensitive search. The N options tells REXX to provide you with line 
numbers when reporting hits. Normally, REXX reports only the 
string, not the line number within the search file. 


-)i(- SYSFILETREE (fr./es, I/ari.ab/e, [Opfi.ons], I 771ffrt.bu/es], 


[NAffrl.bwfes]) Use this function to search for the files specified by 
the F/'/es variable. You can use wildcard characters within the search 
criteria. War/.ab/e is an array that contains the results of the search 
upon return from the function. Element 0 of the array contains the 
total number of array entries. 


The Opf/'or7s parameter allows you to search for specific file types. 
You can use the following options: 8 (default setting of files and 
directories), D (directories only), F (files only), 0 (report only fully 
qualified filenames), S (scan subdirectories recursively), and T (return 
time and date in the form YY/MM/DD/HH/MM). You can combine the 
options to achieve various effects. 


The 774ffr/.bufes and IVAffr/.bufes options allow you to work with 
specific file attributes. The 774ffr/.bL/res variable allows you to specify a 
search attribute. The IVAffr/'bufes variable allows you to specify a new 
attribute for the files that you find. Each attribute variable uses a 
positional mask in the following order: archive, directory, hidden, 
read-only, and system. You use the following symbols within the 
mask: * (attribute is either set or clear, it doesn't matter which), + 
(attribute set), and -(attribute clear). For example, if you wanted to 
search for files with the hidden and system attributes set you would 
use the following mask: **+*+. Likewise, if you wanted to reset the 
archive attribute of a file you would use the following mask -****. As 
you can see, it is quite simple to search for and change attributes 
using this method. 


-`i`.,'`- SNSGETEAIUFilename, ExtendedAttr.IbuteName, Variable) 


Use the SYSGETEA function to retrieve an extended attribute from a 
file. It returns 0 if the function succeeds. F/'/er)ame contains the name 
of the file that you want to examine. Exfer}dec/Affr/'bufelvame is the 
name of the extended attribute that you want to look for. Use 
War/'ab/e to hold the results of the search. 


-*- SYSGETKEYflopfl.on]) Use this function to retrieve a key from 


the keyboard buffer. If there is no keystroke in the buffer, the function 
waits until the user presses a key. Unlike the standard CHARIN() 
function, the user does not need to press Enter to return the 
keystroke. 


There are two options you can use with this function. ECHO is the 
default setting. REXX automatically echoes any keystrokes to the 
display. NOECHO retrieves the keystroke without displaying it on 
screen. This is a useful setting for applications like password entry 
screens where you wouldn't want anyone to see the keystrokes typed 
by the user. 


-*- SYSGETMESSAGE(rvumber, [Fi./e], [Sfri.ng J] ,... [Sfring9]) 


Instead of using the standard method to define messages for your 
application, you can use the SYSGETMESSAGE function to retrieve 
them from a file. The default file is OS0001.MSG. Using a file allows 
you to provide National Language Support (NLS) with your 
application. Instead of creating a new version of your application for 
each nationality, you can simply create different message files-one 
for each language that you want to support. IVur77ber contains the 
number of the message you want to use within the file. F/'/e contains 
the name of a file that you want to use as a message source. You 
must use the MKMSGF utility to build this file. Sir/'ng7 through 
Sir/.ngg are variables used as replacement strings. They replace the 
°/ol through °/o9 parameters contained in the message string file. 


-)i(- SYSMKDIR(Dl.rectory) Use this function to create a new 


directory. It returns one of the following codes to signal success or 
failure: 


0 Directory created successfully 
2 FileNotFound 
3 PathNotFound 
5 Access Denied 


26 NotDOSDisk 
87 Invalid parameter 


108 Drive Locked 
206 Filename Exceeds Range Error 


3t(-SYSOS2VER() The sYSOS2VER function returns a string 


containing the current OS/2 version number in the form x.xx. 


-`,`.,'`- S;NSPUFTEAI(Filename, ExtendedAttributeName , Variable) 


Use this function to write an extended attribute to a file specified by 
Filename. ExtendedAttri.buteName COIT+atns the name Of the extended 
attribute to write to the file. Var/'ab/e contains the value that you want 
to write to the file. This function returns a 0 if it succeeds. 


-)i(- SYSQUERYCLASSLIST I/.sf Use this function to obtain a list of 


active object classes. i/.sf is an array that contains the information on 
return from the call. Element 0 of the array contains the number of 
items in the list. 


-*- SYSREGISTEROBJECTCLASS(C/assrvame, Modu/ervame) 


Use this function to register a new object class definition. C/asslvame 
contains the name of the class that you want to register. 
Mocyu/elvame contains the name of the file that contains the 
definition of the object class. All object class definitions appear in a 
SOM DLL. The function returns 1 if successful or 0 if unsuccessful. 


-)i(-SYSRMDIR(Ditecfory) The SYSRMDIR function removes the 


specified directory from the drive. It returns one of the following 
error codes to indicate success or failure: 


0 Directory Deleted successfully 
2 File NotFound 
3 PathNotFound 
5 Access Denied 


16 Current Directory 
26 NotDOSDisk 
87 Invalid parameter 


108 Drive Locked 
206 Filename Exceeds Range Error 


-*-SYSSEARCHPATH(Path, I/./ename) Use this function to 


search for a file within the specified path. The function returns the 
fully qualified filename if it finds the file. Otherwise, it returns a blank 
string. Pafh contains the path that you want to search. F/'/ename 
contains the file that you want to search for. This function will not 
allow you to use wildcard characters. 


-*-SYSSETICON(F/./ename, /conrvame) This function allows you 


to assign a particular icon to a file. Filename contains the name of 
the file that you want to change. /conlvame is the name of an icon 
filename. You must use OS/2 specific icons; files from other 
operating systems/environments will not work. The function returns a 
value of 1 if it set the icon. It returns a value of 0 if the function fails. 


-*- SYSSLEEP(Seconds) Use this function to put the application to 


sleep for a specific amount of time. 


-*- SYSTEMPF[LENAME(7eT mp/ate, [Fi./fer]) You can use the 


SYSTEMPFILENAME function to obtain the name of a file or 
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directory that does not currently exist. This allows you to quickly 
create a temporary file without overwriting an existing file by 
mistake. The Temp/are variable contains a string that defines the 
temporary filename that you want returned. It contains filter and 
mandatory characters. REXX creates a filename containing all the 
mandatory characters in the specified positions. It fills the filter 
character positions with numbers. The standard filter character is the 
question mark (?). However, you can use any character that you want 
to for a filter by specifying a value in the F/./fer variable. 


-*- SYSTEXTSCREENF{EAD(Row, Co/ermn, [£ength]) This 


function retrieves the character information contained on a text 
screen. f?ow contains the starting row, and Co/umr7 contains the 
starting column. You would use values of 0 for f?ow and 0 for 
Co/umn if you wanted to start at the very beginning of the screen. 
The optional Lengfh variable allows you to specify how many 
characters to return. The default setting reads until it reaches the end 
of the screen. This function does not store any color information. As 
a result, if you store a screen, then later restore it, the new screen 
will not contain any of the color information of the original. The 
SYSREADSCREEN function does retain any carriage returns and line 
feeds found in the original screen. 


-*-SYSTEXTSCREENSIZE0 Use this function to determine the 


number of rows and columns in the current screen. It returns a string 
containing the number of rows as the first entry and the number of 
columns as the second entry. 


-*-SYSWA[TNAMEDPIPE(rvame, [7i.meod/I) This function 


allows you to perform a timed wait on a particular named pipe. 
Ivame contains the name of the pipe in the form \PIPE\P/'pelvame. 
The optional I/.meoL/i value allows you to specify how long the 
function should wait for the named pipe before it returns. Using a 
value of 0 tells REXX to use the default timeout period. A value of -1 
specifies an unlimited wait period. Any other positive value is the 
time to wait in microseconds. DOSWAITNAMEDPIPE always returns 
one of the following values: 


0 Named Pipe is no Longer Busy 
2 Named pipe Not Found 


231 Function Timed Out Before Named Pipe Became Available 


Table 1 -3 


-)i(- TIMEflopfl.on]) Use this function to display the current time. The 


TIME function normally displays the time in military format 
HH..MM..SS. Like the DATE function, you can add an option to 
change the form of the TIME function output. Table 1-3 shows the 
available formats. 


The REXX TIME( ) function formats 


Format Description 


Long Format-Shows the complete time in military format (24-hour 
clock) including hundredths of a second. 


Hours-Shows the number of hours since midnight. 


Minutes-Shows the number of minutes since midnight. It uses the 
equation (Hours x 60) + Minutes to determine the total number of 
minutes. 


Seconds-Shows the number of seconds since midnight. It uses the 
equation (((Hours x 60) + Minutes) x 60) + Seconds to determine the 
total number of seconds. 


Normal Time-Use this option to display the time in normal format. 
You can obtain the same results by not using any option at all. 


Civilian Format-Shows the time in am/pin format (12-hour clock) 
instead of military format. 


-)i(- TRACEfloption]) Returns the trace options currently in effect. 


You can check for a specific trace option by specifying the first 
character of the option in Option. See the TRACE command for 
further details. 


-*- TRANSLATE(S/r/.ng I, [Oqtpd/I I, I/npd/I I, Pad]]]) This 


function allows you to substitute one character in a string for another. 
Sir/.r7g contains the string that you want to translate. OL/fpuf contains 
the string that you want to use in the final result in place of the string 
specified by Input. If /r7Puf is larger than Oufput, REXX substitutes 
spaces for the missing characters. You can change this default by 
adding a value to Pad. 


-)i(-TRUNC(rvumber, [P/aces]) Normally, the TRUNc function 


returns the integer part of IVL/mber. It does not perform any 
rounding. You can modify this behavior by supplying a value for 


P/aces. This tells REXX how many decimal places to preserve in the 
result. 


-)i(- VALUE(rvame I, [rvewt/a/qe] I, Se/ecfor]]) Returns the current 


value of the variable specified by Ivame. You optionally can assign a 
new value to Ivame by providing it in Ivewva/ue. This function 
normally looks at internal variables only. You can specify external 
variables by providing a value for Se/ec for. For example, if you use 
OS2ENVIF30NMENT for Se/ec for, then you can look at OS/2 
environment variables. 


-*- VEFtlFY(S/rT.ng, Refeiience I, [Opf7.on] I, Sfa/'/]]) This function 


returns a value that indicates whether all characters in Sfr/'r7g also 
appear in f?eferer7ce. If not, it returns a number that indicates the first 
nonmatching character. Verify returns 0 if all the characters match. 
You can change this default behavior by adding a value to Opf/'on. N 
(nonmatch) is the standard behavior. M (match) finds the first character 
in Sir/.ng that matches f?eferer7ce instead of finding the first 
nonmatching character. Normally, VERIFY starts at the first character 
of Sir/.r7g. You can specify an alternate starting point with Sfarf. 


-*- WOFtD(S/rl.ng, Pps/t7.on) Returns the word at the position 


specified by Pos/i/'or7 in Sir/.ng. If you specify a position that is larger 
than the number of words in Sir/.ng, WORD returns a null string. 


-)i(- WOF{D[NDEX(S/r/.ng, Pps/tr.on) Returns the first character of 


the word at the position specified by Pos/I/`on in Sir/.r7g. If you specify 
a position that is larger than the number of words in Sir/'r7g, 
WORDINDEX returns a blank character. 


-*- WORDLENGTH(S/rl.ng, Pos/.fjon) Returns the length of the 


word at the position specified by Pos/I/'on in Sir/'r7g. If you specify a 
position that is larger than the number of words in Sir/'ng, 
WORDLENGTH returns 0. 


-)i(- WORDPOS(Search, String I, Sfarf]) Searches for the string 


contained in Search within the string Sir/.r7g. It returns the position 
of the first word in Sir/'ng that matches Search. Normally, 
WORDPOS starts at the first word of Sir/.r7g. You can specify a 
different starting position using Sfarf. 


-*- WORDS(String) Returns the number of blank delimited words in 


String. 


-*- XRANGEflsfarf] I, End]) This function returns a string with all 


the codes between Sfarf and Er7c}. For example, if you used 
XPANGE(a, d), the function would return a string containing "abcd." 
The default value for Sfarf is Ooh. The default value for Er7c/ is FFh. 
You can specify hexadecimal sequences by following the code 
character with an X. 


-*- X2B(Hexsfrfrog) Converts a hexadecimal string to a binary string. 


The resulting string is four times longer than the original and does 
not contain any blanks. 


-*-X2C(Hensfring) Converts a hexadecimal string to ASCII 


characters. Each two character hexadecimal sequence becomes one 
character. You can place spaces at word boundaries in the string for 
ease of reading. REXX automatically pads the left side of the string 
with a 0 if there are an uneven number of hexadecimal digits. 


-)i(- X2D(Hexsfring I, £ength]) Converts a hexadecimal string to a 


decimal string. Ler7gfh contains the length of the resulting string. 
REXX pads the string with zeros as required to create a string of the 
desired length. 


PMREXX functions 


OS/2 provides a GUI environment for users. As a result, REXX also 
needs to provide constructs to handle that GUI environment. The 
following paragraphs describe functions that you can use under 
PMREXX in addition to those listed in the previous section. As you 
can see, this list of functions provides everything that you need to 
create a reasonably complex application using REXX as the base 
language. Even though you could build a complete application using 
these constructs, REXX really is suited for short utility projects. 
Remember, REXX is essentially a glorified batch language. 


-*-FtxMessageBox(7eTi¥/, [7/i/e], [Bdffon], I/con]) You use this 


function to create a message box. Text contains the information that 


you want to appear in the message box. There is almost no limit to 
the messages that you can provide the user. The optional Buff on 
variable tells REXX the type and number of buttons that you want to 
display on screen. 


Programming 


Every REXX program starts with the same line: a comment field. 
Some people simply place a blank comment at the top of their REXX 
file, but you can use it for a lot more. If you create more than a few 
batch files to automate your everyday work, it becomes necessary to 
document them in some way. Using this initial comment to leave 
yourself a note about some of the particulars of this particular file can 
reduce confusion later and make your program easier for someone 
else who uses it. A standard REXX program should begin with the 
following entries as part of the comment: 


/* Name: Your Name 


Date: Date of Initial Prograln Creation 
Purpose: The purpose of this prograln. 
Notes: Any notes about the program in general. Some people 
include psuedocode (a form of programmers notation) here. 


*/ 


Of course, you can modify this initial entry any way you see fit. 
However, the more information you put here, the less frustration 
you'll have later when it's time to modify your program. 


-)i(- Expressions One of the more powerful features of REXX is its 


ability to interpret expressions. There are two forms of expression 
that you will use quite often in your REXX programs. The first form 
is string concatenation. For example, if you type the following 
statements : 


Varl = "Hello" 
Var2 = "World" 
Var3 = Varl + Var2 
S;A:X VElr3 


you will see Hello World displayed on your screen. Concatenation is 
useful when you want to combine program text with user input. 
Often, you'll use it as part of information or result screens. 


Table 1 -4 


The other form of expression is the result of an equation. REXX 
provides quite a few math operators as shown in Table 1-4. 


The REXX math operators 


Operator Description 


Adds two numbers together. For example, 2 + 4 results in an output 
of6. 


Subtracts one number from another. For example, 4 - 2 results in 
an output of 2. 


Multiplies one number by another. For example, 4 * 2 results in an 
output of 8. 


Divides one number by another. For example, 5 / 2 results in an 
output of 2.5. 


Returns only the integer portion of a division. For example, 5 0/o 2 
results in an output of 2. REXX truncates the decimal portion of the 
answer. 


Returns only the decimal portion of a division. For example, 5 // 2 
returns an output of .5. REXX removes the integer portion of the 
result. 


Changes the normal order of precedence. REXX normally evaluates 
the multiplication and division portion of an expression first, then 
the addition and subtraction. It also evaluates an expression from 
left to right, just like you normally would read it. For example, 2 + 3 
/ 2 results in an output of 3.5. Using the parenthesis will force 
REXX to evaluate the part of the expression you want evaluated 
first. For example, (2 + 3) / 2 results in an output of 2.5 instead of 
the 3.5 that you received before. You can nest the parenthesis as 
needed to achieve the desired result. For example, 2 + (3 + 4) / 2 
results in an answer of 5.5, while (2 + (3 + 4)) / 2 results in 4.5. 


-*- Formatting There are a variety of formatting techniques that 


people use to increase the readability of their batch files. One system 
is not necessarily better than any other. However, you should use a 
system of some sort to help you read your batch files. 


Indentation is one way that people use to format their programs. For 
example, if you want to make a control structure obvious, you can 
format it as follows: 


±F SomeExp 


THEN 


Do Something 


ELSE 


Do Something Else 


As you can see, this is a lot more readable than placing all the 
statements in a straight line. There is no doubt that this is a control 
structure or where each of the elements end. 


Another form of formatting is capitalization. For example, you could 
type all REXX commands in all uppercase, variables with initial 
capital letters only, and OS/2 commands in all lowercase. Using this 
formatting scheme reduces confusion when you edit your batch file. 
There is no doubt which words are variables, which are REXX 
commands, and which are OS/2 commands. 


These are just a few ways that you can make your batch files easier to 
read and modify. As you become more proficient at creating REXX 
programs, you probably will find other ways to improve the 
appearance and readability of your code. 


-)i(- Getting down to business Now that you know what elements 


make a REXX program, it's time to start putting them together. 
Menuing systems are one of the projects that many people tackle 
using a batch programming language. While OS/2 reduces the need 
for using such a menuing system, you still can use one for commands 
that you must execute from the OS/2 prompt. The following 
program shows one simple way of using REXX to automate a process 
using a menuing system: 


/* NAME: Your Name 


DATE: 8/23/92 
PURPOSE: This program shows you how to create a menuing systeni using REXX. */ 


Answer = 0 /* Initialize our answer variable. */ 
DO WIIILE \(Answer=3) /* Do this procedure until the user enters Quit. */ 


CLS /* Clear the display */ 
SAY DATE ( ) 
SAY TIME ( ) 
SAY CEN'I`ER("This is my menu", 80) /* Center the heading. */ 
SAY 
SAY "1. Display the current directory" 
SAY "2. Change drive and/or directory" 


SAY "3. Quit" 
SAY "Enter your selection" 
PULL Answer 
SELECT 


WHEN Answer = 1 


THEN CALL DispDir 


WIIEN Answer = 2 


THEN CALL Chnglt 


OTHERWISE 


SAY "Good-bye" 


END 


END 
EXIT 


/* This function displays the directory on screen, then returns 


the user to the original menu. Some OS/2 commands require 
that you enclose them in quotes. Otherwise, REXX assumes that 
they are internal commands and processes them. 


*/ 


DispDir: 
cls 
dir ":more" /* Surround MORE with quotes it will execute. */ 
SAY "Press any key when ready. . . " 
PULL 
RETURN 


/* 'Ihis function allows the user to change the current drive and directory. */ 


Chnglt : 
cls 


/* Get the new drive from the user, then change it. */ 


SAY "Enter a new drive or press Enter to retain the current drive. " 
PULL Drive 
IF \(Drive = I") /* If user pressed Enter, ignore change. */ 


THEN Drive" : " 


/* Get the new directory from the user, then change it. */ 
SAY "Enter new directory or press Enter to retain current one. " 
PULL Directory 
IF \(Directory = "') /* If user pressed Enter, ignore change. */ 


THEN CD Directory 


RETURN 


As you can see, this menuing system is quite simple to create and it 
does automate the process of performing a task under OS/2. In many 


cases, a menuing system can do more than just help you when you 
don't remember a specific command. It can prompt you for the 
correct information. For example, in this example program, the 
menuing system prompts you for the information that is needed to 
change drive and directory. You don't have to remember the 
command itself , simply what you wanted to do with it. 


Automating your work 
environment through the 
Workplace Shell 


The Workplace Shell (WPS) provides the means to automate your 
work environment in several ways. First, unlike DOS programming, 
you do not need to close, then reopen the environment before you 
switch between programming and debugging. Even though modern 
IDEs make this task automatic, you still waste time switching between 
environments under DOS. Under Windows, you had to worry about 
overloading the environment by opening too many windows at the 
same time. Under the WPS, both of these problems are solved. You 
can write, compile, test, and debug your application by simply 
switching windows without any loss of speed. Of course, this form of 
automation becomes very obvious once you think about it. 


However, there are other automation features of the WPS that you 
might not think about using. For one thing, you can use REXX to 
duplicate the batch files that you use under DOS. REXX provides 
much greater flexibility as you can see from the previous section. 
Making optimal use of the features that REXX provides can greatly 
reduce the time that you need to perform tasks. Under OS/2, you 
can perform many of these tasks in the background. For example, 
how many times have you waited for a printout of your application 
before you could proceed to fix some critical bug? Under OS/2, you 
can perform this task in the background while you work on some 
other section of the program. Using REXX to automate some of 
these tasks could reduce your participation level to almost nothing. 


Using the WPS to full advantage requires a change in thinking as 
well. You need to plan ahead if you want to use its full capability. For 


example, you could use an automated test program to test your 
application in the background while you print some of your program 
modules and edit yet other modules. The keyword here is planning. If 
you don't plan to use these capabilities, then you won't make the best 
use of the programming environment. In coding, the bottom line is 
not only to get your code written well, but fast. 


Finally, you can arrange the desktop to meet a variety of needs and 
work styles. Some people leave their desktop a mess, which is fine 
if you work better in a disorganized environment; however, most 
people do benefit from a little organization. For example, you 
could place all your drives and other devices at the bottom of the 
screen, as shown in Fig.1-1. This makes them handy when you're 
in the middle of an application and need to check something. 
Instead of minimizing your application, you can simply open the 
new one by double clicking one of the drive icons. Another good 
practice is to place your applications and application folders at the 
top of the screen. This allows you to grab them quickly without 


RE i,i ill ® di if gr ffi 
RIRE Games Communications Tlmecheck Other Word BoilandHe|p Boiland I++ 


P'ocesslng 


i :a gl 


0S`2S}istem 


® 


Information 


•§;:\x:a; 


Master Help Index 


Lk ffl 


``.`i`` ` 


Minimized 


Window Vlewer 


^fg:;i 


Templates 


f»ife ¥¥S i-i¥;i ;_-al as SSS fry?us 


EpsonLQ85o DrlveA DnveB Dwec DnveD DrlveE shiedder 


OS/2 Workplace Shell (WPS). 


minimizing your current application. It usually helps to place all 
your OS/2 default folders at the side of the screen since you 
normally won't use them with other applications. 


You can go even further in the optimization process by setting 
application settings to optimize that application's environment. 
Choosing to minimize an application to the desktop saves time when 
you use several applications together. Using the default setting keeps 
applications out of the way when you don't need them. Cluttering 
your display with excess icons is the last thing you want to do when 
programming. 


No amount of planning for OS/2's multitasking environment removes 
the work that you need to do. That is a constant that remains 
unchanged no matter what environment you propose to use. 
However, the fact that you can use tools to automate part of the 
process is a real help in a world full of deadlines. 


Optimizing the 
programming environment 


Once you optimize the OS/2 environment as a whole, you need to 
optimize your programming environment. This usually involves 
several steps that you might or might not perform automatically. Like 
most optimizations, this one starts at product installation. Have you 
ever noticed how many software packages install more extraneous 
than useful files? Magazines and books both make money telling you 
how to rid yourself of this excess baggage. While you will always end 
up with a few extraneous files, there are a number of ways that you 
can reduce the clutter. The following paragraphs provide some 
suggestions you can use: 


> Only create the libraries that you need for current projects 


when you install your compiler. Most (if not all) compiler 
installation programs provide the means for adding new 
libraries later. Extra libraries simply take space, and there is no 
guarantee that you will need them later. 


> Some compiler packages allow you to choose which features 


to install. Take the time required to read the vendor manual 
before you start the installation. Install only those features 
that you actually will use; any additional features will waste 
space and slow down the environment without any substantial 
payback. Some programmers install these extra features 
thinking that they will take the time to learn them later. 
Always wait until you have the time to learn to use a new 
feature before you install it. 


> You can save a substantial amount of hard disk space by not 


installing online help if you don't use it. Some programmer's 
force themselves to use online help, even though it makes 
them less productive. Other programmer's never touch the 
documentation, relying exclusively on the online help. Still 
other programmer's install the online help and never use it. If 
you fall into the first or third categories, think about how you 
plan to use the online help before you install it. Likewise, if 
you fall into the paper documentation category, you might 
want to print any README files, then erase them from your 
hard disk. 


> Never select the default installation. This is the best way to 


ensure that the programming environment that you get won't 
meet your needs. If you want an environment that makes the 
most of the time you spend programming, always select the 
custom installation option. 


Figure 1-2 shows a typical compiler installation screen. Notice the 
two buttons at the top of the dialog box. The first one allows you to 
change the default tools and library options, the other allows you to 
change the miscellaneous options. 


Clicking the Tools and Library button displays the dialog box shown 
in Fig. 1-3. Notice that every box in the dialog box is checked. This 
means that, if you used the default installation, you would encumber 
your hard disk with every feature of this compiler. There is no way 
that the vendor can predict what pieces of the compiler that you will 
need, so this is a very predictable setup. You need to change this 
configuration to meet your needs or suffer the consequences of an 
overly full hard disk that might slow your work. 
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Borland C++ Main 
Installation dialog box. 


Borland C++ Installation Options 
dialog box. 


Once you get your compiler installed, take the time to check a few 
things out. For example, changing the size of your disk cache can 
make a significant difference in the speed of compilation. While you 
could perform this task in the background, very few programmers do 
so unless they want to perform a complete compilation of an entire 
application. Because this is one of the foreground tasks that you'll 
perform, it pays to optimize compilation speed as much as possible. 
Check out the compilation speed of several average sized modules 
using different cache sizes and other settings, then set the cache size 
to the one that gives you best performance. 


Check out the operation of your debugger on your largest 
application. Make sure that you use settings that offer the best speed, 
memory usage, and least risk of compiler-induced errors. Nothing is a 
bigger time waster than thinking that you have a bug in your 
application, only to find out later that you had set your debugger up 
wrong. Take the time to perform the setups on your editor and other 
utilities as well. 


Figure 1 -2 


One size fits all usually doesn't work. You usually need to perform 
some setups for each application that you build. While most 
programming environments provide some method of saving your 
compiler environment from one session to the next for each 
application, they don't save the settings for your debugger and other 
utilities. You might want to keep a disk file or printed output with 
these settings. That way, you can quickly restore them when you need 
to take an application out of storage. 


You can use these suggestions as a starting place for creating your 
own customized programming environment. However, it's only a 
start. Take a little time now to make things as easy as you can. The 
little time that you spend now can net big savings later. For example, 
a minute might not seem like much when it comes to compilation 
speed. However, over hundreds of compilation cycles, that minute 
starts to build into hours, then days. You effectively could save 
yourself days of programming effort in a year by reducing the time it 
takes to compile an application. Seconds taken from the time it takes 
to perform a repetitive task almost always pay big dividends later. 


Creating a complete 
test environment 


There is a whole world of ideas for testing applications. There isn't 
room in this book to explore them all, but we can take a look at several 
different test environments. Each of the following paragraphs looks at 
one test method that you can employ to test your application. 


The most common test method is to get a number of beta testers to 
check your application for problems. The viability of this method is 
directly proportional to how your beta test group represents the 
people who normally use your application. If you use a sufficient 
number of beta testers who represent a wide enough variety of 
environments, you should deliver a fairly bug-free application. Of 
course, there are more variables than first meets the eye. For 
example, how do you know your beta testers actually are reporting 
every problem or even using the application? As you can see, even 
though this method is theoretically good, implementation details could 
prove difficult. 


Some vendors turn to in-house testers using automated test suites to 
supplement their beta testers. This has several advantages and 
disadvantages. The advantages include the ability to test your 
application using the same sequence of steps every time that you test it. 
Using automated testing software means that you can perform the test 
in the background while you do something more productive in the 
foreground. Of course, there is no way that you can test every possible 
combination of keystrokes or even make sure that the keystrokes that 
you do test are reasonable in the real world. As a result, most vendors 
who use automated test suites create them from reproducible problems 
submitted by beta testers. Part of the input for a bug report includes the 
keystrokes that reproduce the error. You can tie these keystrokes 
directly into the test suite to make sure that the bug gets fixed and that 
no interaction bugs pop up to break the software again. 


Some vendors employ directed testing. This method uses task scripts 
that new or experienced users follow. The vendor has observers 
stationed behind one-way glass to observe the reactions of the testers 
as they perform the tasks. Not only can this help the vendor improve 
the usability of a product, but it can alert the vendor to logic errors in 
the product as well. The biggest disadvantage to this test method is 
that it costs a lot. The vendor might make a big investment in labor- 
intensive testing that might not yield significant results. 


You also can use keystroke recording to test the application. The 
vendor creates a special version of the program that records each 
user keystroke to a file on disk. The software also records the test 
environment, hardware conditions, and specific performance 
measures as part of the file. Each error that the user encounters also 
appears in the file. This method provides the vendor with superior 
test and usability analysis materials. The big disadvantage to this 
method is getting the beta testers to return the file to the vendor. 
There isn't much that you can do to evaluate the performance of 
your application unless you can get consistent returns from your 
users. Another problem with this approach is that you can't test 
everything. As a result, you cannot test everything that you need to 
check to ensure the application runs reliably. 


As you can see, testing is part science, part art, part luck, and part 
magic. Coming up with the right test methods and techniques could 


easily require an entire book by itself . Suffice it to say that these 
techniques will get you started on the right track. Honing these 
methods to a set of tests that always produce the desired results 
requires both time and patience. 


Using the Developer 
Connec+ion for OS/2 


The Developer Connection provides you with many tools in addition 
to the ones that you'll find with the standard OS/2 package. One 
item that it usually contains is a set of the latest OS/2 operating 
system beta components. This means that you can buy the Developer 
Connection and not need to worry if you are developing for the latest 
version of OS/2. There also is a complete set of other IBM beta 
products (a beta version of a C++ compiler for example) provided 
with the package. The first version of this product includes a full copy 
of OS/2 version 2.1, but there is no guarantee that IBM will include it 
with future versions of the product. Some of the items provided with 
the first Developer Connection disk include: 


> Multimedia Presentation Manager/2 Version 1.1 


> Multimedia UltiMotion 


> Motion Video AVI Files 


> Communications Manager for OS/2 (single user) 


> Networking Services/DOS (NSDOS) 


> PL/I Workstation/2 


> TCP/IP for OS/2 


> Hyperwrite 


> PM Automated Test Environment (PMATE) 


> Workstation Interactive Test Tool (WITT) 


It's the additional items that really add value to the Developer 
Connection. There isn't room here to provide you with a detailed 
description of every product on the current disk; besides, the contents of 


each disk are different. However, the following paragraphs do provide 
you with an overview of the features in some of the more interesting 
applications. I chose to concentrate on the most interesting applications 
that you should see with every version of Developer Connection. You'll 
need to use them to find out just how easy they are to use and which 
tools apply to your particular situation. Make sure you don't read the 
description and decide that these tools aren't for you. Take the time to 
actually test them; descriptions often leave out important applications 
that you will see immediately. 


One of the big reasons to buy this package is the documentation. 
This is a constant for Developer Connection; you will always receive 
the latest OS/2 documentation. The first version of the product 
includes the following documentation: 


> OS/2 Technical Library 


> Communications Manager Technical Library 


> REXX information 


> TCP/IP information 


> Using Workplace OS/2 


> Pen for OS/2 Developer's Toolkit information 


Presentation Manager Automated 
Test Environment (PMATE) 


I talked about the importance of testing in a previous section of this 
chapter. One of the biggest obstacles to companies actually 
implementing these solutions is the cost involved. After all, test software 
doesn't come for free; it usually costs a great deal more than companies 
are willing to pay. In essence, automated test software is the UPS of the 
computer industry. Very few companies can justify the cost of using a 
UPS on each workstation even though it makes sense to do so. Some 
companies fall into the same trap with software testing, leaving it up to 
some specialized department that doesn't even interact with the 
department responsible for software development (or worse yet, not 
doing much in-house testing at all). PMATE resolves this problem when 
programming under OS/2. Figure 1-4 shows the main menu of this 


Figure 1 -4 


Presentation Manager 
Automated Test 
Environment 
(PMA;TE) main 
window. 


utility. You get this automated test environment as part of the Developer 
Connection. It is located in the PMATE subdirectory of the TSTTOOLS 
directory on your CD-ROM. As a result, management is happy about the 
bottom line and the programmers are happy because they have the 
proper tools. 


As you can see, the PMATE screen looks essentially like an editor. It 
allows you to record, load, and run script files that test your application. 
More importantly, PMATE provides a batch mode that you can call from 
within a REXX application. This means that you could compile and test 
your application in the background without ever leaving your foreground 
session. You still need to perform the setups required to make this work. 
While the payoff on large projects can more than pay for the time 
required to set up this level of automation, you might want to consider 
its feasibility on small projects. 


Production tools 


The PRODTOOL directory contains a number of production tools 
that you can use to enhance your program. More importantly, some 
of these tools could serve as inspiration for your own application; 
they show some of the things that you can do with a typical OS/2 
application. Some of these tools provide a standalone environment 
that you enhance using macros; other tools simply provide the 
programmer with useful information. For example, PM Globe is a fun 
program that you can run from REXX using macros. This means that 


you could put on a show using this application, shut it down, then go 
on to do some other work with your REXX application. Figure 1-5 
shows the PM Globe display. As you can see, there is nothing earth 
shaking about this application, but it does serve to show how you can 
use some of the utilities provided with the Developer Connection. 
One interesting feature of this application is the distance calculator 
shown in the lower left corner of the screen. 
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PMGlobe main u)indow. 


Dlnfo is one of those utilities that fall into the useful category even if 
it doesn't provide any command-line interface that you can use within 
a REXX application. Essentially, this application tells you about the 
swap file for your system. The default statistics include the 
SWAPPER.DAT size and the amount of free space. You can include 
several other statistics including two alarms. 


PMTree is more than a simple tool that you can use to dress up an 
application, and it really falls outside the utility category as well. This 
application provides the programmer with essential information about 
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the PM environment. Figure 1-6 shows a typical PMTree display. 
Notice that this is a hierarchical display of all the active PM windows. 
The leftmost window provides a description of all the properties of 
that window. Double clicking on another window displays a 
description of its properties and children. As you can see from the 
figure, PMTree displays the process ID, thread ID, and other 
characteristics of the "head" window. You can use this information to 
see how other developers arrange their applications or as part of the 
debugging effort for your own applications. The number of uses is 
virtually unlimited. 


PMTree main u)indow. 


There are many other production tools provided as part of the 
Developer Connection. All of them fall into one of the three 
previously described areas. As you can see, each tool provides an 
added level of productivity that you can rely on to help you in your 
programming endeavors. 


Editors 


It might not seem like a programmer would need yet another editor 
for creating applications. Yet, the D6veloper Connection provides 
f our rather unique editors that you can use to create your 
applications. Rather than simply assume that the editor provided with 
your compiler will do all the work that you need it to do, you might 
want to take a look at one or more of these useful utilities. 


Tiny (T.EXE in the TINYED subdirectory of the EDITORS directory) is 
an editor that consumes a mere 9K of RAM. One of the unique 
features of this editor is that it is a DOS application; you can use it 
anywhere within OS/2 or when you boot DOS to check something 
out during the development cycle. For this reason, Tiny is more 
useful than many editors that you might want to use. In addition, its 
small memory f ootprint means that you can load all but the very 
largest source code files. The flexibility provided by this editor even 
allows you to write documentation or other longer texts. Tiny can't 
provide all the bells and whistles of a full-featured word processor, but 
it does the job in a pinch. 


SlickEdit is a fully functional programmer's editor. It provides the 
hooks required to make it an integrated development environment 
(IDE) if you want. For example, there are built-in menu commands for 
compiling your application. The IDE even includes a limited number 
of debugging aids like finding the last error recorded by the compiler. 
Figure 1-7 shows the SlickEdit display. One of the unique features of 
this editor is that it comes in versions f or a variety of operating 
systems including DOS and Windows NT. This means that you could 
learn one interface for all the environments that you use. 


EPM is another one of the editors included with the Developer 
Connection. This one should look familiar to anyone who has used the 
enhanced editor provided with OS/2 (Fig. 1-8). Essentially, this is an 
exact copy of that editor. The only difference is that the Developer 
Connection provides the tools for you, the programmer, to modify the 
behavior of this power editor. The package includes one very important 
tool to assist you in this goal. The macro compiler allows you to create 
add-ons to the enhanced editor that you can distribute to users of your 
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Slick Edit main window. 
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E macros are compiled Into .ex f iles, which are interpreted at run time. 
You can control the macros at two levels. One is bu creating a MYCNF.E 
and setting f lags in lt which controls which of the various features 
we've alreadg written are included ln the .ex files; the second is to 
actuallg write gour own macros. The configuration flags are described in 
the User's Guide - enter the command VIEW EPMUSERS to see it. The macro 
language is defined and described in the EPM Macro Programmer.s Technical 
Reference - enter VIEW EPMTECH to see lt. Also, looking through the 
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product or use for a variety of other purposes. Besides the macro 
compiler, the Developer Connection provides some debugging aids and 
documentation for creating macros for EPM. 


The fourth editor, Hyperwrite/E, really is not an editor in the 
conventional sense. What it provides is an advanced help and 
documentation creation utility. It provides an environment where you 
can create fully animated help and documentation files that really help 


the user understand your application. This includes both graphics and 
sound, besides the usual toolbars and other aids associated with a 
hypertext environment. Of course, it takes time and patience to learn to 
use a tool of this nature. The Developer Connection also provides a 
number of training aids in the form of samples that you can use to learn 
this product. (You also will find a tutorial conspicuously located under 
the Help menu.) Figure 1-9 shows a typical screen from Hyperwrite/E. 
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Hyperwrite/E includes several aids besides the editor. For example, it 
includes a compiler that allows you to create either a HLP file that 
you can call within an application or an INF file you execute from the 
OS/2 prompt. The output looks much like any other help screen that 
you might have used in the past. The big difference is the ease with 
which you create it and the ability to add both graphics and sound. 


As you can see, the editors provided with the Developer Connection 
help you to automate a variety of tasks. Don't pass up the 
opportunity to use these rather unique tools; add them to your 
programmer`s toolbox as soon as possible. Especially important is the 
Hyperwrite/E editor. This is one tool that can greatly reduce the time 
required to document your new application. 
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he processor represents the central control for any 
application that you create. It's a combination traffic cop 


and "brain" for your computer system. Just about everything that 
goes on in your computer goes through the processor first. Using 
the maximum level of commands for the platform that you want to 
target with your application ensures that it will run as quickly as 
possible. For example, it is much faster to push all the registers 
on the stack at one time using the PUSHA command rather than 
pushing them one at a time. Using this command also ensures 
that you will not run into any bugs associated with popping the 
registers in a different order than you push them. So using the 
appropriate command set for the platform that you want to target 
not only makes the application run faster, but your debugging time 
less as well. 


This chapter discusses processor-specific commands. It arranges 
them in mnemonic alphabetical order within functional areas. 
There are sections for the 8086/8088, 8087, 80286, 80287, 
80386, 80387, and 80486 processors. Each general-purpose 
processor builds upon the commands available to its predecessor; 
therefore, each command appears once. The math coprocessor 
commands require a little different treatment. While each math 
coprocessor does build on the capabilities of its predecessor, some 
math coprocessor commands do not appear in all versions of the 
chip. As a result, the applicable processor appears in parentheses 
beside the command. 


8086/8088 and 8087 commands 


The following paragraphs describe each 8086/8088 processor 
specific command. Table 2-1 lists the 8086/8088 processor 
instructions by functional area. The 80286, 80386, 80486, and 
Pentium processors use these commands as well. Table 2-2 lists the 
8087 math coprocessor commands. The 80287, 80387, and 80487 
math coprocessors use some of these commands as well. Each 
command identifies which processor uses it. 


Table 2-1 8088/8086 command summary 


Command 


Arithmetic instructions 


ASCII Adjust for 
Addition (AAA) 


ASCII Adjust for 
Division (AAD) 


ASCII Adjust for 
Multiplication (AAM) 


ASCII Adjust for 
Subtraction (AAS) 


Add with Cany (ADC) 


Add Without Carry 
(ADD) 


Convert Byte to Word 
(CBW) 


Compare (CMP) 


Convert Word to 
Doubleword (CWD) 


Decimal Adjust for 
Addition (DAA) 


Decimal Adjust for 
Subtraction (DAS) 


Decrement (DEC) 


Divide (DIV) 


Integer Divide (IDIV) 


Description 


The ASCII Adjust for Addition instruction changes the AL register 
contents from packed to unpacked decimal format. Zero the 
auxiliary carry flag (AF) before using this command. 


The ASCII Adjust for Division instruction changes the AX register 
contents from unpacked to packed decimal format. 


The ASCII Adjust for Multiplication instruction corrects the result of 
multiplying two unpacked decimal format numbers. 


The ASCII Adjust for Subtraction instruction corrects the results of 
subtracting of two unpacked decimal format numbers. Zero the 
auxiliary carry flag (AF) before using this command. 


Use the Add with Carry instruction to add two numbers and 
accounts for carries generated from previous additions. 


This instruction adds two operands without regard for CF status. 


This instruction converts a byte value stored in AL to a word value 
by extending the sign-bit in AL through AH. 


This instruction compares by subtracting the value of the destination 
from the value of the source. It updates the AF, CF, OF, PF, SF, and 
ZF registers to reflect the subtraction results but does not place the 
results in the destination. 


Use this instruction to convert a word value to a doubleword value. 
It extends the sign-bit in AX through DX. 


The Decimal Adjust for Addition instruction corrects the result of 
adding two packed decimal operands. 


The Decimal Adjust for Subtraction instruction corrects the result of 
subtracting two packed decimal operands. 


This instruction reduces the contents of a register or memory 
variable by one. 


The divide instruction performs unsigned division. It divides the 
quantity in the accumulator by the divisor. When using byte values, 
the quotient appears in AL and the remainder appears in AH. The 
value divided appears in AX. When using word values, the quotient 
appears in AX and the remainder appears in DX. The value divided 
appears in the AX:DX register pair. Using doubleword values places 
the quotient in FAX and the remainder in EDX. The processor 
divides the numerator in the EAX:EDX register pair by the divisor. 


The Integer Divide instruction performs signed division on the value 


Command 


Integer Multiply 
(IMUL) 


Increment (INC) 


Multiply (MUL) 


Negate (NEG) 


Subtract with Borrow 
(SBB) 


Subtract (SUB) 


Description 


contained in the accumulator. When using byte values, the quotient 
appears in AL and the remainder appears in AH. The value divided 
appears in AX. When using word values, the quotient appears in AX 
and the remainder appears in DX. The value divided appears in the 
AX:DX register pair. Using doubleword values places the quotient in 
EAX and the remainder in EDX. The processor divides the 
numerator in the EAX:EDX register pair by the divisor. 


This instruction performs signed multiplication on the value in the 
accumulator by the multiplicand. When using byte values, the AX 
register contains the double length result. Using word values returns 
the result in the AX:DX register pair. Doubleword values return a 
result in the EAX:EDX register pair. 


This instruction increases the contents of a register or memory 
variable by one. 


This instruction performs unsigned multiplication on the value in the 
accumulator by the multiplicand. When using byte values, the AX 
register contains the double length result. Using word values returns 
the result in the AX:DX register pair. Doubleword values return a 
result in the EAX:EDX register pair. 


This instruction calculates the two's complement of the destination 
operand. This is effectively the same as subtracting the destination 
operand from 0. 


This instruction subtracts the source value from the destination 
value and stores the result in the destination. It decrements the result 
by one if CF = 1. The subtract with borrow instruction affects AF, 
CF, OF, PF, SF, and ZF. 


The subtract instruction subtracts the value in the source from the 
destination. It affects AF, CF, OF, PF, SF, and ZF. 


Bit-manipulation instructions 


Logical AND on Bits 
(AND) 


Logical NOT on Bits 
(NOT) 


Logical OR on Bits 
(OR) 


Rotate Left through 
Carry (RCL) 


Use this instruction to logically AND two values together at the bit 
level. 


The NOT instruction produces the one's complement of the 
destination operand by inverting its bits. This instruction does not 
affect any flags. 


This instruction performs an inclusive OR of the source and 
destination operands. It places the results in the destination operand. 
A bit equals 1 in the destination operand when either or both 
operands contain a 1 in that bit position. 


This instruction rotates the bits in the destination to the left the 
number of places specified in the count operand. The carry flag 
receives the value dropped from the high-order bit. The low-order 
bit receives the value contained in the carry flag. 


Table 2-1 Continued 


Command 


Rotate Right through 
Carry (RCR) 


Rotate Left (ROL) 


Rotate Right (ROR) 


Arithmetic Shift Left 
(SAL) 


Arithmetic Shift Right 
(SAR) 


Shift Left (SHL) 


Shift Right (SHR) 


Test Bits (TEST) 


Logical Exclusive-OR 
on Bits (XOR) 


Description 


This instruction rotates the bits in the destination to the right the 
number of places specified in the count operand. The carry flag 
receives the value dropped from the low-order bit. The high-order 
bit receives the value contained in the carry flag. 


This instruction rotates the bits in the destination to the left the 
number of places specified in the count operand. It affects both OF 
and CF. 


This instruction rotates the bits in the destination to the right the 
number of places specified in the count operand. It affects both OF 
and CF. 


The Arithmetic Shift Left instruction shifts all bits in the destination 
operand left the number of bits specified by the source operand. It 
affects CF, OF, PF, SF, ZF, and AF (undefined). 


The Arithmetic Shift Right instruction shifts all bits in the destination 
operand right the number of bits specified by the source operand. It 
affects CF, OF, PF, SF, ZF, and AF (undefined). 


The Shift Left instruction shifts all bits in the destination operand left 
the number of bits specified by the source operand. It affects CF, 
OF, PF, SF, ZF, and AF (undefined). 


The Shift Right instruction shifts all bits in the destination operand 
right the number of bits specified by the source operand. It affects 
CF, OF, PF, SF, ZF, and AF (undefined). 


This instruction performs a logical AND of two operands then 
updates the flags. The flags reflect how the two operands compared. 
Test does nothing with the results. The flags it affects include CF, 
OF, PF, SF, ZF, and AF (undefined). 


This instruction performs an exclusive OR on two operands. It 
returns a value in the destination operand. XOR sets a bit in the 
destination operand if the corresponding bits in the comparison 
opperands are different. The exclusive or instruction affects CF, OF, 
PF, SF, ZF, and AF (undefined). 


Control-transfer instructions 


Execute a 
Subprogram (CALL) 


The call instruction executes a subprogram. Two types of call 
instruction exist. The first type is a near call to subprograms ±32 
Kbytes or less distant from the current instruction. For this type, the 
processor updates IP to the next instruction position and pushes this 
value on the stack. It then places the new instruction value in IP and 
continues execution until a return instruction appears. The second 
type is a far call to subprograms greater than ±32Kbytes distant 
from the current instruction. The processor pushes CS and replaces 
it with the segment of the call instruction. Then, the processor 


Command 


Software Interrupt 
(INT) 


Interrupt on Overflow 
(INTO) 


Return from Interrupt 
(IRET) 


Jump if Above (JA) 


Jump if Above or 
Equal (JAE) 


Jump if Below (JB) 


Jump if Below or 
Equal (JBE) 


Jump on Carry (JC) 


Jump if CX Equals 
Zero (JCX) 


Jump if Equal (JE) 


Jump if Greater Than 
(JG) 
Jump if Greater Than 
or Equal (JGE) 


Jump if Less Than 


Description 


updates IP to the next instruction position and pushes this value on 
the stack. It then places the new instruction value in IP and 
continues execution until a return instruction appears. 


This instruction activates the following interrupt processing 
procedure: (1) Decrement SP by 2. Push the flags on the stack using 
the same format as PUSHF. (2) Clear TF and IF to prevent other 
single-step or maskable interrupts from occurring. (3) Decrement SP. 
Push CS. (4) Calculate the interrupt pointer address by multiplying 
the interrupt type by four. Place the second word of the interrupt 
pointer in CS. (5) Decrement SP, and push IP. Place the first word of 
the interrupt pointer in IP. 


The assembler generates a 1-byte form of the instruction for 
interrupt 3 (known as the breakpoint interrupt). Only device drivers 
or operating systems normally create their own interrupt code. The 
only flags affected are IF and TF, which the interrupt processor sets 
tol. 


Use this instruction to generate an interrupt 4 when the overflow 
flag (OF) equals 1. It operates in all respects like the interrupt 
instruction when executed. If OF equals 0, the processor ignores this 
instruction. 


This instruction returns control to a procedure calling an interrupt 
after the interrupt completes. It pops CS, IP, and all flags. 


This instruction transfers control to the instruction pointed to by IP 
+ Displacement when CF and ZF equal 0. 


This instruction transfers control to the instruction pointed to by IP 
+ Displacement when CF equals 0. 


This instruction transfers control to the instruction pointed to by IP 
+ Displacement when CF equals 1. 


This instruction transfers control to the instruction pointed to by IP 
+ Displacement when CF or ZF equal 1 . 


This instruction transfers control to the instruction pointed to by IP 
+ Displacement when CF equals 1. 


This instruction transfers control to the instruction pointed to by IP 
+ Displacement when CX equals 0. 


This instruction transfers control to the instruction pointed to by IP 
+ Displacement when ZF equals 1. 


This instruction transfers control to the instruction pointed to by IP 
+ Displacement when SF equals OF or ZF equals 0. 


This instruction transfers control to the instruction pointed to by IP 
+ Displacement when SF equals OF. 


This instruction transfers control to the instruction pointed to by IP 
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Command 


(JL) 
Jump if Less Than or 
Equal (JLE) 


Jump Unconditionally 
(JMP) 


Jump if Not Above 
(JNA) 


Jump if Not Above or 
Equal (JNAE) 


Jump if Not Below 
(JNB) 


Jump if Not Below or 
Equal (JNBE) 


Jump on No Carry 
(JNC) 


Jump if Not Equal 
(JNE) 


Jump if Not Greater 
Than (JNG) 


Jump if Not Greater 
Than or Equal (JNGE) 


Jump if Not Less 
Than (JNL) 


Jump if Not Less 
Than or Equal (JNLE) 


Jump on No 
Overflow (JNO) 


Jump on No Parity) 
(JNP 
Jump on Not Sign 
(JNS) 
Jump on Not Zero 


Description 


+ Displacement when SF does not equal OF. 


This instruction transfers control to the instruction pointed to by IP 
+ Displacement when SF does not equal OF or ZF equals 1. 


This instruction unconditionally transfers control to the instruction 
referenced by an operand. There are three types of unconditional 
jump. The first type, short, allows jumps of only ±127 bytes but 
produces only 2 bytes of code. The second type, near, allows jumps 
of ±32 Kbytes. It produces 3 bytes of code. The third type uses both 
CS and IP for far jumps. It uses 5 bytes of code. 


This instruction transfers control to the instruction pointed to by IP 
+ Displacement when CF or ZF equal 1. 


This instruction transfers control to the instruction pointed to by IP 
+ Displacement when CF equals 1. 


This instruction transfers control to the instruction pointed to by IP 
+ Displacement when CF equals 0. 


This instruction transfers control to the instruction pointed to by IP 
+ Displacement when CF and ZF equal 0. 


This instruction transfers control to the instruction pointed to by IP 
+ Displacement when CF equals 0. 


This instruction transfers control to the instruction pointed to by IP 
+ Displacement when ZF equals 0. 


This instruction transfers control to the instruction pointed to by IP 
+ Displacement when SF does not equal OF or ZF equals 1. 


This instruction transfers control to the instruction pointed to by IP 
+ Displacement when SF does not equal OF. 


This instruction transfers control to the instruction pointed to by IP 
+ Displacement when SF equals OF. 


This instruction transfers control to the instruction pointed to by IP 
+ Displacement when SF equals OF or ZF equals 0. 


This instruction transfers control to the instruction pointed to by IP 
+ Displacement when OF equals 0. 


This instruction transfers control to the instruction pointed to by IP 
+ Displacement when PF equals 0. 


This instruction transfers control to the instruction pointed to by IP 
+ Displacement when SF equals 0. 


This instruction transfers control to the instruction pointed to by IP 


Command 


(JNZ) 


Jump on Overflow 
(JO) 


Jump on Parity (JP) 


Jump on Parity Even 
(JPE) 


Jump on Parity Odd 
(JPO) 


Jump on Sign (JS) 


Jump on Zero (JZ) 


Loop (LOOP) 


Loop While Equal 
(LOOPE) 


Loop While Not 
Equal (LOOPNE) 


Loop While Not Zero 
(LOOPNZ) 


Loop While Zero 
(LOOPZ) 


Return from a 
Subprogram (RET) 


Description 


+ Displacement when ZF equals 0. 


This instruction transfers control to the instruction pointed to by IP 
+ Displacement when OF equals 1. 


This instruction transfers control to the instruction pointed to by IP 
+ Displacement when PF equals 1. 


This instruction transfers control to the instruction pointed to by IP 
+ Displacement when PF equals 1. 


This instruction transfers control to the instruction pointed to by IP 
+ Displacement when PF equals 0. 


This instruction transfers control to the instruction pointed to by IP 
+ Displacement when SF equals 1. 


This instruction transfers control to the instruction pointed to by IP 
+ Displacement when ZF equals 1. 


The Loop instruction decrements CX by 1, then tests to see if CX 
equals 0. If CX is greater than 0, Loop transfers control to the target 
instruction. Otherwise, it passes control to the next inline 
instruction. 


The loop instruction decrements CX by 1, then tests to see if CX 
equals 0. If CX is greater than 0 and ZF equals 1, Loop transfers 
control to the target instruction. Otherwise, it passes control to the 
next inline instruction. 


The loop instruction decrements CX by 1, then tests to see if CX 
equals 0. If CX is greater than 0 and ZF equals 0, Loop transfers 
control to the target instruction. Otherwise, it passes control to the 
next inline instruction. 


The loop instruction decrements CX by 1, then tests to see if CX 
equals 0. If CX is greater than 0 and ZF equals 0, Loop transfers 
control to the target instruction. Otherwise, it passes control to the 
next inline instruction. 


The loop instruction decrements CX by 1, then tests to see if CX 
equals 0. If CX is greater than 0 and ZF equals 1, Loop transfers 
control to the target instruction. Otherwise, it passes control to the 
next inline instruction. 


Use this instruction at the end of a subprogram to return control to 
the calling program. The assembler generates two types of return: 
far and near. The near return pops only IP from the stack. A far 
return pops both IP and CS from the stack. 


Data-transfer instructions 


Input Data from port This instruction allows data input from a port to the Ax register. 
(IN) Use either the Dx register or a constant to specify port number less 
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Command 


Load the AH Register 
with Flags (LAHF) 


Load the DS Register 
(LDS) 


Load the Effective 
Address (LEA) 


Load the ES Register 
(LES) 


Move (MOV) 


Output Data to Port 
(OUT) 


Remove Data from 
the Stack (POP) 


Remove Flags from 
the Stack (POPF) 


Place Data on the 
Stack (PUSH) 


Place Flags on the 
Stack (PUSHF) 


Store AH into the 
Flag Register (SAHF) 


Exchange (XCHG) 


Description 


than 256. For port number greater than 255, use the DX register 
only. This instruction does not affect the flags. 


Use this instruction during assembly language conversions from 
8080/8085 processor to 8086/8088 processor format. It transfers 
the low-order byte of the flags register to AH. The flags transferred 
include SF, ZF, AF, PF, and CF. 


This instruction transfers a 32-bit pointer from the source operand 
(memory only) to the destination operand (offset) and the DS register 
(segment). The destination operand is any 16-bit general purpose 
register. 


The load effective address instruction transfers the offset of the 
source operand (rather than its value) to the destination operand. 
The source operand is always a memory variable. The destination is 
always a general purpose 16-bit register. 


This instruction transfers a 32-bit pointer from the source operand 
(memory only) to the destination operand (offset) and the ES register 
(segment). The destination operand is any 16-bit general purpose 
register. 


This instruction transfers data from the source operand to a 
destination operand of the same length. 


This instruction allows data output to a port from the AX register. 
Use either the DX register or a constant to specify port numbers less 
than 256. For port numbers greater than 255, use the DX register 
only. This instruction does not affect the flags. 


POP removes the word pointed to by the stack pointer (SP) and 
places it in a memory operand or register. It then increments SP by 2. 
POPF removes the word pointed to by the stack pointer (SP) and 
places it in the flag register. It then increments SP by 2. 
PUSH decrements SP by 2. It then adds the word contained in a 
register or memory operand to the location pointed to by the stack 
pointer (SP). 
PUSHF decrements SP by 2. It then adds the flag register contents 
to the location pointed to by the stack pointer (SP). 


Use this instruction during assembly language conversions from 
8080/8085 processor to 8086/8088 processor format. It transfers 
the contents of AH to low-order byte of the flags register. The flags 
transferred include SF, ZF, AF, PF, and CF. 


This instruction swaps the contents of the source and destination 
operands. It does not affect any flags. 


Command 


Translate O{LAT) 


Description 


The translate instruction places the value in a table pointed to by BX 
in AL. The AL register initially contains an offset into the table. The 
translate instruction does not affect any flags. 


Flag- and processor-control instructions 


Clear the Carry Flag 
(CLC) 


Clear the Direction 
Flag (CLD) 


Clear the Interrupt 
Flag (CLI) 


Complement the 
Carry Flag (CMC) 


Escape (ESC) 


Halt (HLT) 


Lock the Bus (LOCK) 


No Operation (NOP) 


Set the Carry Flag 
(STC) 


Set the Direction Flag 
(STD) 


Set the Interrupt Flag 
(STI) 


Wait OvAIT) 


The Clear the Carry Flag instruction sets CF to zero. 


The Clear the Direction Flag instruction sets DF to zero. 


The Clear the Interrupt Flag instruction sets IF to zero. 


This instruction toggles the value of CF. 


The escape instruction provides a means for co-processing chips to 
access data using the 8086/8088/80286/80386 processing 
stream. It causes the processor to place the operand on the bus 
while internally performing a no operation (NOP) instruction. 


This instruction stops the processor temporarily while waiting for an 
interrupt. It provides a means of creating a wait state without 
resorting to endless software loops. The halt instruction does not 
affect any flags. 


The lock instruction prevents interference by any coprocessors 
during the next instruction. Always use lock with other instructions. 


This instruction tells the CPU to do nothing. 


This instruction sets CF reguardless of its present condition. 


This instruction sets DF reguardless of its present condition. 


This instruction sets IF reguardless of its present condition. 


This instuction causes the CPU to enter its wait state until it receives 
an external interrupt on the test line. Wait does not affect any flags. 


String-manipulation instructions 


Compare Strings, 
Byte-by-Byte 
(CMPSB) 


Compare Strings, 


This instruction changes the value of the AF, CF, OF, PF, SF, and ZF 
flags to show the relationship between two bytes in a string. The 
results of the comparison do not affect the contents of either 
operand. After comparing the two string bytes, the instruction 
updates both SI and DI to point to the next string element. DF 
controls the direction of comparison. 


This instruction changes the value of the AF, CF, OF, PF, SF, and ZF 
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Command 


Word-by-Word 
(CMPSW) 


Load a Byte from 
String into AL 
(LODSB) 


Load a Word from 
String into AX 
(LODSW) 


Move String 
Byte-by-Byte 
(MOVSB) 


Move String 
Word-by-Word 
(MOVSW) 


Repeat (REP) 


Repeat if Equal 
(REPE) 


Repeat if Not Equal 
(REPNE) 


Repeat if Not Zero 
(REPNZ) 


Repeat if Zero (REPZ) 


Scan String for Byte 


Description 


flags to show the relationship between two words in a string. The 
results of the comparison do not affect the contents of either 
operand. After comparing the two string words, the instruction 
updates both SI and DI to point to the next string element. DF 
controls the direction of comparison. 


Use this instruction to transfer a byte from the string pointed to by 
SI to AL. The SI register automatically advances to the next string 
element in the direction pointed to by the direction flag. 


Use this instruction to transfer a word from the string pointed to by 
SI to AX. The SI register automatically advances to the next string 
element in the direction pointed to by the direction flag. 


This instruction moves the byte pointed to by SI to the destination 
pointed to by DI. Using the REP instruction with this instruction, 
repeats the move the number of times shown in CX. After each 
move, the instruction advances both SI and DI to the next position 
in the direction indicated by DF. 


This instruction moves the word pointed to by SI to the destination 
pointed to by DI. Using the REP instruction with this instruction, 
repeats the move the number of times shown in CX. After each 
move, the instruction advances both SI and DI to the next position 
in the direction indicated by DF. 


Use this instruction with string manipulation instructions to repeat 
the instruction the number of times specified in CX. 


Use this instruction with string manipulation instructions to repeat 
the instruction the number of times specified in CX. It repeats only 
while ZF = 1 when used with the CMPSB, CMPSW, SCASB, or 
SCAS\^/ instructions. 


Use this instruction with string manipulation instructions to repeat 
the instruction the number of times specified in CX. It repeats only 
while ZF = 0 when used with the CMPSB, CMPSW, SCASB, or 
SCASW instructions. 


Use this instruction with string manipulation instructions to repeat 
the instruction the number of times specified in CX. It repeats only 
while ZF = 0 when used with the CMPSB, CMPSW, SCASB, or 
SCASW instructions. 


Use this instruction with string manipulation instructions to repeat 
the instruction the number of times specified in CX. It repeats only 
while ZF = 1 when used with the CMPSB, CMPSW, SCASB, or 
SCASW instructions. 


Use this instruction with any of the repeat instructions to scan 


Command 


(SCASB) 


Scan String for Word 
(SCASW) 


Store Byte in AL at 
String (STOSB) 


Store Word in AX at 
String (STOSW) 


Description 


strings for the value contained in AL. After each scan, DI advances 
to point to the next string element. This instruction affects AF, CF, 
OF, PF, SF, and ZF. 


Use this instruction with any of the repeat instructions to scan 
strings for the value contained in AX. After each scan, DI advances 
to point to the next string element. This instruction affects AF, CF, 
OF, PF, SF, and ZF. 


Use this instruction alone or with any repeat instruction to send the 
value in AL to the string pointed at by DI. DI automatically advances 
to the next string location after each store operation. This 
instruction does not affect any flags. 


Use this instruction alone or with any repeat instruction to send the 
value in AX to the string pointed at by DI. DI automatically advances 
to the next string location after each store operation. This 
instruction does not affect any flags. 


8087 command summary Table 2-2 


Command 


Arithmetic instructions 


Absolute Value (LABS) 
ifR!f jR;I / grf j#Sn / 
80387) 


Add Real (FADD) 


If%NR;n / grf J%%n / 
80387) 


Add Real and Pop 
(FADDP) 
ifRJNR];fl/grfj#S]/ 
80387) 


Change Sign (FCHS) 
ifRJNR;] / grf jr2:Sn / 
80387) 


Divide Real (FDIV) 


If%f jR;] / grf I;%%n / 
80387) 


Divide Real and Pop 
(FDIVP) 
If%fjR];n/grfj%Sn/ 


Description 


Use this instruction to replace the top stack element with its absolute 
value. It affects the IE status bit. 


The Add Real instruction adds two numbers together and places the 
result in the destination operand. The instruction uses the stack as 
the default destination. This instruction affects the PE, UE, OE, DE, 
and IE status bits. 


This instruction adds two operands, places the result at the 
destination, and pops a value from the stack. The instruction uses 
the stack as the default destination. This instruction affects the PE, 
UE, OE, DE, and IE status bits. 


Use this instruction to change the sign of the top stack element. It 
affects the IE status bit. 


This instruction divides the destination by the source operand. It 
places the result in the destination. The instruction uses the stack as 
the default destination. The divide real instruction affects the PE, 
UE, OE, ZE, DE, and IE status bits. 


This instruction divides the destination by the source operand. It 
places the result in the destination and pops the stack. The 
instruction uses the stack as the default destination. The divide real 
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Command 


80387) 


Divide Real Reversed 
(FDIVR) 
rRiR!f j%] / orf jf Is] / 
80387) 


Divide Real Reversed 
and Pop (FDIVRP) 
ifR!f jR;n / 8/i jr2:S] / 
80387) 


Integer Add (FIADD) 
rRiR!f jR;I / 8/i jr2:S] / 
80387) 


Integer Divide (FIDIV) 
ifR!fjR];fl/grfj#S]/ 
80387) 


Integer Divide 
Reversed (FIDIVR) 
ifRJfJR];n/gr!;2Sn/ 
80387) 


Integer Multiply 
(FIMUL) 
ifRf jR;n / grj#S] / 
80387) 


Integer Subtract 
(FISUB) 
ifRJf jR;I / 8/i J#S] / 
80387) 


Integer Subtract 
Reversed (FISUBR) 
liR!NR;J / orf j#8J / 
80387) 


Multiply Real (FMUL) 
ifRJf JR;] / grf jf Is] / 
80387) 


Multiply Real and Pop 
(FMULP) 


Description 


and pop instruction affects the PE, UE, OE, ZE, DE, and IE status 
bits. 


This instruction divides the source by the destination operand. It 
places the result in the destination. The instruction uses the stack as 
the default destination. The divide real reversed instruction affects 
the PE, UE, OE, ZE, DE, and IE status bits. 


This instruction divides the source by the destination operand. It 
places the result in the destination and pops the stack. The 
instruction uses the stack as the default destination. The divide real 
reversed and pop instruction affects the PE, UE, OE, ZE, DE, and IE 
status bits. 


This instruction adds two operands as integers and stores the result 
at the destination. It assumes a default stack destination. The integer 
add instruction affects the PE, OE, DE, and IE status bits. 


The integer divide instruction divides the destination by the source 
operand as integers. It stores the result in the destination operand. 
The instruction uses the stack as the default destination. If affects the 
PE, UE, OE, ZE, DE, and IE status bits. 


The integer divide reversed instruction divides the source by the 
destination operand as integers. It stores the result in the destination 
operand. The instruction uses the stack as the default destination. It 
affects the PE, UE, OE, ZE, DE, and IE status bits. 


The integer multiply instruction multiplies the destination by the 
source operand as integers. It stores the result in the destination 
operand. The instruction uses the stack as the default destination. It 
affects the PE, OE, DE, and IE status bits. 


This instruction subtracts the source from the destination operand 
and places the result in the destination. The instruction assumes a 
stack default destination. The arithmetic instruction affects the PE, 
OE, DE, and IE status bits. 


This instruction subtracts the destination from the source operand 
and places the result in the destination. The instruction assumes a 
stack default destination. The arithmetic instruction affects the PE, 
OE, DE, and IE status bits. 


This instruction multiplies the source by the destination operand. It 
stores the result in the destination operand. The instruction assumes 
a default stack destination. The multiply real instruction affects the 
PE, UE, OE, DE, and IE status bits. 


This instruction multiplies the source by the destination operand. It 
stores the result in the destination operand, then pops the stack. 


Command 


lfR/i jR;] / grj%%fl / 
80387) 


Partial Remainder 
(FPREM) 
ifRJf JR;I / grf jr2:Sn / 
80387) 


Round to an Integer 
(FRNDINT) 
rRiR!NR;n/8/Nr2:Sn/ 
80387) 


Square Root (FSQRT) 
IfR!f jR;] / 8/i j%Sn / 
80387) 


Subtract Real (FSUB) 
ifR!f jR;n / 8/i j%Sn / 
80387) 


Subtract Real and 
Pop (FSUBP) 
rRiR!fjR;]/8/ff2S]/ 
80387) 


Subtract Real 
Reversed (FSUBR) 
ifRJf JR;I / grN#S] / 
80387) 


Subtract Real 
Reversed and Pop 
(FSUBRP) 
If%f jR;n / grj%%n / 
80387) 


Extract Exponent and 
Significand 
(EXTRACT) 
ifR!f jR;] / 8!N#8] / 
80387) 


Description 


The instruction assumes a default stack destination. The multiply real 
instruction affects the PE, UE, OE, DE, and IE status bits. 


The partial arctangent instruction calculates the modulo of the top 
two stack elements. It performs this by successively subtracting the 
second element from the first. The calculated remainder remains in 
the first element. The instruction affects the CO, C1, C3, UE, DE, 
and IE status bits. 


This instruction rounds the number located on the top stack element 
to an integer. It affects the PE and IE status bits. 


Use this instruction to calculate the square root of the top stack 
element. The square root value replaces the old stack value. This 
instruction affects the PE, DE, and IE status bits. 


This instruction subtracts the source from the destination operand 
and places the result in the destination. The instruction assumes a 
default destination of stack. It affects the PE, UE, OE, DE, and IE 
status bits. 


This instruction subtracts the source from the destination operand 
and places the result in the destination. Upon instruction 
completion, it pops the stack. The instruction assumes a default 
destination of stack. It affects the PE, UE, OE, DE, and IE status 
bits. 


This instruction subtracts the destination from the source operand 
and places the result in the destination. The instruction assumes a 
default destination of stack. It affects the PE, UE, OE, DE, and IE 
status bits. 


This instruction subtracts the destination from the source operand 
and places the result in the destination. It pops the stack upon 
instruction completion. The instruction assumes a default destination 
of stack. It affects the PE, UE, OE, DE, and IE status bits. 


This instruction pops the top stack element, separates the exponent 
from the significand, and pushes both values on the stack. It affects 
only the IE status bit. 


Comparison instructions 


Compare Real 
(FCOM) 
liR!NR;I / orf jf Is] / 
80387) 


This instruction compares the top stack element with the second 
stack element or other specified operand. It affects the CO, C1, C3, 
DE, and IE status bits. 
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Command 


Compare Real and 
Pop (FCOMP) 
if#fjR];fl/grNffs]/ 
80387) 


Compare Real and 
Pop Twice (FCOMPP) 
liRJf JR;J / orf j#SJ / 
80387) 


Integer Compare 
(FICOM) 
ifa/I jR;] / grf j%Sn / 
80387) 


Integer Compare and 
Pop (FICOMP) 
ifR!f jR;n / grf j#f fn / 
80387) 


Test (FTST) 
if%f jR;n / grf :;%S] / 
80387) 


Examine (FRAM) 


IfR!f jR;n / grf j%%n / 
80387) 


Constant instructions 


Load Value of 1.0 
(FLD1) 
rRiR!fjR;I/orfjr2:8]/ 
80387) 


Load Value of log2e 
(FLDL2E) 
If%f jR;] / grf j%%n / 
80387) 


Load Value of log210 
(FLDL2T) 
ifRf!/R];n/8!fjrrs]/ 
80387) 


Load Value of logio2 
(FLDLG2) 
ifR!f jR;n / grf jr2:S] / 
80387) 


Load Value of loge2 


Description 


This instruction compares the top stack element with the second 
stack element or other specified operand. It then pops the stack. 
The compare real and pop instruction affects the CO, C1, C3, DE, 
and IE status bits. 


This instruction compares the top stack element with the second 
stack element or other specified operand. It then pops the stack 
twice. The compare real and pop instruction affects the CO, C1, C3, 
DE, and IE status bits. 


This instruction converts the operand to an integer (if required) and 
compares it to the top stack element. It then changes the condition 
of the status word bits to match the comparison result. The status 
word bits affected include CO, C2, C3, DE, and IE. 


This instruction converts the operand to an integer (if required) and 
compares it to the top stack element. It then changes the condition 
of the status word bits to match the comparison result and pops the 
stack. The status word bits affected include CO, C2, C3, DE, and IE. 


This instruction compares the top stack element with zero and sets 
the status bits accordingly. It affects the CO, C2, C3, DE, and IE 
status bits. 


This instruction examines the top stack element and updates the 
status bits to reflect its condition. The examine instruction affects the 
CO, C1, C2, and C3 status bits. 


This instruction pushes the constant 1.0 on the stack. It affects the 
IE status bit. 


This instruction pushes the value of log2e onto the stack. It affects 
the IE status bit. 


This instruction pushes the value of log210 onto the stack. It affects 
the IE status bit. 


This instruction pushes the value of log]o2 onto the stack. It affects 
the IE status bit. 


This instruction pushes the value of loge2 onto the stack. It affects 


Command 


(FLDLN2) 
ifRJf jR;n / grf j#Sn / 
80387) 


Load Value of Pi 
(FLDPI) 
IfR!f jR;n / grf j%%n / 
80387) 


Load Value of 0.0 
(FLDZ) 
ifRJf IR;n / 8!f jr2:S] / 
80387) 


Description 


the IE status bit. 


This instruction pushes the value of Pi onto the stack. It affects the 
IE status bit. 


This instruction pushes 0 onto the stack. It affects the IE status bit. 


Data-transfer instructions 


BCD Load (FBLD) 
ifRJf jR;] / 8!f j#S] / 
80387) 


BCD Store and POP 
(FBSTP) 
ifRJf JR;] /grNr2:S] / 
80387) 


Integer Load (FILD) 
ifRJf J%] / 8if !r2:S] / 
80387) 


Integer Store (FIST) 
if%NR;n / grf I 2%] / 
80387) 


Integer Store and Pop 
(FISTP) 
If%f jR;fl / grf j%%] / 
80387) 


Load Real (FLD) 
if%f jR;n / grf :;%g] / 
80387) 


Store Real (FST) 
liR!f jR;] / grf jr2:S] / 
80387) 


Store Real and Pop 
(FSTP) 
if#f JR;] / orf jr2:Sn / 
80387) 


Exchange Registers 
(FXCH) 
IfR!f IR;] / grf j%%fl / 
80387) 


Use this instruction to convert a BCD number (at the specified 
operand address) to a temporary real format and pushes it on the 
stack. This instruction affects the IE status bit. 


This instruction pops a value from the stack, converts it to a BCD 
integer, and places it at the operand address. It affects the IE status 
bit. 


This instruction converts the binary integer pointed to by the 
operand address to a temporary real format and pushes it on the 
stack. It affects only the IE status bit. 


Use this instruction to round the top stack element to a binary 
integer and store it at the operand address. This instruction affects 
the PE and IE status bits. 


Use this instruction to round the top stack element to a binary 
integer and store it at the operand address. It pops the stack after 
storing the integer. This instruction affects the PE and IE status bits. 


Use this instruction to push the source operand on the stack. It 
affects the DE and IE status bits. 


The store real instruction copies the top stack element value to the 
position pointed to by the destination operand. This instruction 
affects the PE, UE, OE, and IE status bits. 


The store real instruction copies the top stack element value to the 
position pointed to by the destination operand. It pops the stack 
after transferring the value. This instruction affects the PE, UE, OE, 
and IE status bits. 


This instruction switches the value contained in the top stack 
element with the destination operand. It only affects the IE status bit. 


Table 2 -2 Continued 


Command D escription 


Processor-control instructions 


Clear Exceptions with 
Wait (FCLEX) 


ifRJf jR;n / 8!f jr2:Sn / 
80387) 


Decrement the Stack 
Pointer (FDECSTP) 
if#f JR;] / grf j#Sfl / 
80387) 


Disable Interrupts with 
Wait (FDISI) 
(8087 Only) 


Enable Interrupts with 
Wait (FENI) 
(8087 Only) 


Free Register (FFREE) 
ifR!fjR];n/grfj%%]/ 
80387) 


Increment the Stack 
Pointer (FINCSTP) 
ifRJNR;n / 8/i j#Sn / 
80387) 


Initialize the Processor 
with Wait (FINIT) 
ifRJf !lR;n / 8/i j#g] / 
80387) 


Load a Control Word 
(FLDCW) 
if%f J%n / grf j%%n / 
80387) 


Load the Environment 
(FLDENV) 
ifRJf jR;n / 8/i jr2:S] / 
80387) 


Clear Exceptions 
(FNCLEX) 
ifR!f jR;] / 8!f jr2:S] / 
80387) 


Disable Interrupts 
(FNDISI) 


Precede this instruction with a CPU wait prefix. It clears the 8, PE, 
UE, OE, ZE, DE, IE, and IR status bits. 


This instruction decrements the 8087 status word stack pointer. It 
affects only the ST status bits. 


Precede this instruction with a CPU wait prefix. It sets the IBM 
control word bit preventing the 8087 from generating interrupts. 
This instruction does not affect the status word. 


Precede this instruction with a CPU wait prefix. It clears the IEM 
control word bit allowing the 8087 to generate interrupts. This 
instruction does not affect the status word. 


This instruction changes the specified stack register tag to indicate 
an empty element. It does not affect the status word. 


This instruction increments the stack status word bits. 


This instruction equals a hardware reset instruction for the math 
coprocessor chip. Precede this instruction with a CPU wait prefix. 


Use this instruction to load the control word with the value pointed 
to by the source operand. This instruction does not affect any status 
bits. 


The load the environment instruction restores all the environment 
variables from the 14-word memory location pointed to by the 
source operand. It affects all the status bits. 


Use this instruction to clear the exception flags, interrupt request, 
and busy flags of the status word without using a CPU wait prefix. It 
affects the 8, IR, PE, UE, OE, ZE, DE, and IE status bits. 


This instruction sets the interrupt enable mask of the control word 
without using a CPU wait prefix. It prevents the coprocessor from 


Command 


(8087 Only) 


Enable Interrupts 
(FNENI) 
(8087 Only) 


Initialize Processor 
(FNINIT) 
ifRJf jR;] /grf j#S] / 
80387) 


No Operation (FNOP) 
ifR!f JR;] / 8!f j#8] / 
80387) 


Save State (FNSAVE) 
ifRJf jR;I /grf I 2S] / 
80387) 


Store Control Word 
(FNSTCW) 
ifRJf IR;I / grf j#g] / 
80387) 


Store Environment 
(FNSTENV) 
IfRJfjR];fl/grfjr2:Sn/ 
80387) 


Store Status Word 
(FNSTSW) 
ifRJf JR;] / grf jr2:g] / 
80387) 


Restore State 
(FRSTOR) 
liR!f jR;I / grNr2:S] / 
80387) 


Save State with Wait 
(FSAVE) 
rRiR!ffR;I/orfJ#S]/ 
80387) 


Store Control Word 
with Wait (FSTCW 
ifRJNR;I / grf jr2:S] / 
80387) 


Description 


issuing interrupts. The disable interrupts instruction does not affect 
any status bits. 


This instruction clears the interrupt enable mask of the control word 
without using a CPU wait prefix. It enables the coprocessor to issue 
interrupts. The disable interrupts instruction does not affect any 
status bits. 


This instruction initializes the math coprocessor without issuing a 
CPU wait prefix. It is functionally equivalent to a hardware reset. 


This instruction tells the CPU to do nothing. This instruction does 
not affect the status bits. 


This instruction saves the contents of all math coprocessor registers 
and environment variables, without issuing a CPU wait, to the place 
pointed to by the destination operand. It requires 94 words of 
memory per save for an 8087 math coprocessor. The instruction 
then issues the equivalent of an FNINIT instruction. 


This instruction copies the control word to the place pointed to by 
the destination operand without using a CPU wait prefix. It does not 
affect any status bits. 


This instruction copies the environment variable to the place pointed 
to by the destination operand without using a CPU wait prefix. The 
store requires 14 words when using an 8087 math coprocessor. It 
does not affect any status bits. 


This instruction copies the status word to the place pointed to by the 
destination operand without using a CPU wait prefix. It does not 
affect any status bits. 


This instruction restores the state of all registers and environment 
variables from the location pointed to by the destination operand. It 
affects all the status bits. 


This instruction saves the contents of all math coprocessor registers 
and environment variables to the place pointed to by the destination 
operand. It uses the CPU wait prefix and requires 94 words of 
memory per save for an 8087 math coprocessor. The instruction 
then issues the equivalent of an FINIT instruction. 


This instruction copies the control word to the place pointed to by 
the destination operand using a CPU wait prefix. It does not affect 
any status bits. 


Table 2-2 
Continued 


Command 


Store Environment 
with Wait (FSTENV) 
ifRf JR;n / grf j%Sn / 
80387) 


Store Status Word 
with Wait (FSTSW 
rRFR!NR;] / orf J#X] / 
80387) 


CPU Wait (FWAIT) 
if%fjRn;n/grf!%%]/ 
80387) 


Description 


This instruction copies the environment variable to the place pointed 
to by the destination operand using a CPU wait prefix. The store 
requires 14 words when using an 8087 math coprocessor. It does 
not affect any status bits. 


This instruction copies the status word to the place pointed to by the 
destination operand using a CPU wait prefix. It does not affect any 
status bits. 


The CPU wait instruction performs essentially the same function for 
the math coprocessor as it does for the main processor. This permits 
synchronization of both processors. The main processor suspends 
operations until the coprocessor completes its activities. 


Trancendental instructions 


Value of 2X - 1 
(F2XM1) 
ifRJf jR;I / grf 2x] / 
80387) 


Partial Arctangent 
(FPATAN) 
ifRJf jR;I / 8/i jr2:g] / 
80387) 


Partial Tangent 
(FPTAN) 
ifRJf IR;n / 8!Nr2:S] / 
80387) 


Scale (FSCALE) 
if#f jR;] / grf I/I Is] / 
80387) 


Value of Y X log2 X 
(FYL2X) 
ifRJNR];n/8/f!/r2:S]/ 
80387) 


Yxal:e|?f(#i2oxgp|) 
IfR/f jR;] / grf I 2%n / 
80387) 


This instruction calculates the value of Y = 2X -1. X is the top stack 
element. Y replaces X as the top stack element. This instruction 
affects the PE and UE status bits. 


This instruction computes a = ARCTAN (Y/X), where X is the top 
stack element and Y is the second stack element. It pops both stack 
elements and places the result on the stack. This instruction 
performs no input number validation. It affects the PE and UE status 
bits. 


This instruction computes Y/X = TAN (a) where a is the top stack 
element. The instruction replaces the top stack element with Y, then 
pushes the computed X. This instruction performs no input value 
checking. It affects the PE and IE status bits. 


Use this instruction to calculate the value of X = X x 2Y, where X is 
the value of the top stack element and Y is the second stack 
element. This instruction affects the UE, OE, and IE status bits. 


Thhe]St::StsTa|:t£°e|ec:]ec:tLaat:atSe]sva+:es::ozn5s¥a:±°ei3¥:nY.hfrheex]S 
instruction pops both stack elements and pushes the new value, Z, 
onto the stack. This instruction does not validate the input values. It 
affects the PE status bit. 


±h{{sst{#:t::;t{s°t:ccka:#eenstt::dvaJu{:t°hfezs=coYn5's:g8k(¥ie+m]e)LtYiehr: 
instruction pops both stack elements and pushes the new value, Z, 
onto the stack. This instruction does not validate the input values. It 
affects the PE status bit. 


All the 80x86 processors allow you to monitor conditions through 
the use of a flag register. Each flag provides feedback on a specific 
area. For example, the overflow flag tells you when a processor 
overflow occurs. The flags used for various 8086/8088 instructions 
include the following: 


> Overflow (OF) 


> Direction (DF) 


> Interrupt (IF) 


> Trap (TF) 


> Sign (SF) 


> Zero (ZF) 


> Auxiliary Carry (AF) 


> Parity (PF) 


> Carry (CF) 


The math coprocessor can greatly enhance the execution speed of 
math intensive applications. It makes use of several coprocessor 
specific commands to tell you what type of coprocessor (if any) you 
have installed in your machine. The program reports an 80486 
machine as having an 80387 coprocessor installed because there is 
no difference in functionality. As with the 8086/8088 processor 
example, this example appears in assembly language for maximum 
clarity of the coprocessor specific commands. There are no listings 
for BASIC, C, and Pascal because it is impossible to see the 
coprocessor commands using these languages. In most cases, these 
languages invoke the math coprocessor automatically when detected. 
(Detection and use of the math coprocessor by high-level languages is 
determined by the library support you load within the application.) 


The 8087/80287/80387 math coprocessors do not use flags to 
provide your application with status information. (Remember that the 
80486 comes with built-in math coprocessor support. The 80486SX 
chip provides math coprocessor support through the 80487 math 
coprocessor-essentially the other half of a fully functional 80486DX 
chip.) They use a status and control word instead. The status word 


indicates the current math coprocessor condition. The control word 
affects math coprocessor operation. The breakdown for both the 
control word and status word is shown here: 


Status Word (bit) 
0 Invalid operation Exception (IE) 
1 Denormalized operation Exception (DE) 
2 Zero Divide Exception (ZE) 
3 Overflow Exception (OE) 
4 Under flow Exception (UE) 
5 Precision Exception (PE) 
7 Interrupt Request (IR) 
8 Condition code o (CO) 
9 Condition code 1 (C1) 
10 Condition code 2 (C2) 
11-13 Stack Top pointer (ST) 
14 Condition code 3 (C3) 
15 Busy signal (B) 


Control Word (bit) 
0 Invalid operation Exception Mask (IM) 
1 Denormalized operation Exception Mask (DM) 
2 Zero Divide Exception Mask (ZM) 
3 Overflow Exception Mask (OM) 
4 Under flow Exception Mask (UM) 
5 Precision Exception Mask (PM) 
7 Interrupt Enable Mask (IEM); 0 = Enabled,1 = Disabled 
8-9 Precision control (PC); 00 = 24 bits, 01 = (Reserved),10 = 


53 bits,11 = 64 bits 


10-11 Rounding Control (RC); 00 = Round to Nearest or Even, 01 


= Round Down,10 = Round Up,11 = Truncate 


12 Infinity control (IC); 0 = Projective,1 = Affine 
13-15 Reserved 


Each math coprocessor contains 8 stack elements that are 80 bits 
long. Bits 11 through 13 of the coprocessor status word tell you 
which element appears at the top of the stack. For example, if 
element 8 was at the top of the stack, then element 1 would appear 
second. Each element uses a floating point format consisting of 64 
significant bits, 15 exponent bits, and 1 sign bit. The coprocessors 


use these stack elements for most math operations. Figure 2-1 
depicts the relationship between the stack elements. It also shows 
how the math coprocessor stores real numbers. 


Math coprocessor 
internal logical structure. 


ITFTFTFTITHITFT 


8087/80287/80387 


Stack Structure 


(Each Element 80 Bits Wide) 


iB= 


Word Integer 


80 Bits/72 Magnitude 


Temporary Peal 


I Magnitude/Significand 


EBiased Exponent 


Hsign Bit (1) 


|Not Used/Ignored 


80286 and 80287 
command additions 


The 80286 really added little functionality to the DOS programmer's 
toolbox; even the 80286's protected mode is of dubious value. The 
80287 math coprocessor added even less. The 80286 did add a few 
interesting commands that can reduce your workload. For example, 
the 80286 instruction set adds the PUSHA and POPA instructions. 
Table 2-3 lists the 80286 processor additions to the 8086/8088 
instruction set, while Table 2-4 lists the 80287 coprocessor additions 
to the 8087 instruction set. See Table 2-1 for a listing of 8086/8088 
processor instruction by functional area and Table 2-2 for a listing of 
8087 instructions. 


Table 2-3 80286 command summary 


Command D escription 


Bit-manipulation instructions 


Adjust RPL Field of Use this instruction to compare the two RPL bits (bits o and 1) of 
Selector (ARPL) the first operand with those in the second. If the RPL bits of the first 


operand are less than those of the second, the instruction sets the 
first operand's RPL bits equal to those of the second. The adjust 
RPL field of selector instruction affects ZF only. It then sets ZF. 
Otherwise, this instruction clears ZF. 


Data-transfer instructions 


Input string from This instruction allows string input from a port to the destination 
Port (INS) operand. Use the Dx register to specify the port number and the DI 


register to specify destination. The instruction automatically switches 
between word or byte to accommodate the size of the destination 
operand. This instruction does not affect the flags. 


Input String Byte 
from Port (INSB) 


Input String Word 
from Port (INSW) 


Load Access-Rights 
Byte (LAR) 


Load Global 
Descriptor Table 
Register (LGDT) 


Load Interrupt 
Descriptor Table 
Register (LIDT) 


Load Local Descriptor 
Table Register (LLDT) 


Load Machine Status 
Word (LMSW) 


This instruction allows byte input from a port to the destination 
operand. Use the DX register to specify the port number and the DI 
register to specify destination. This instruction does not affect the 
flags. 


This instruction allows word input from a port to the destination 
operand. Use the DX register to specify the port number and the DI 
register to specify destination. This instruction does not affect the 
flags. 


This instruction overwrites the high byte of the destination with the 
access-rights byte and zeros the low byte. The instruction operates 
only when the discriptor appears at the current privilege level and at 
the selector RPL. The instruction sets ZF when successful. 


Use this instruction to load the global descriptor table from the 
memory address operand specified. The global descriptor table is six 
bytes long. Normally this instruction appears in protected mode 
operating system software only. It does not affect any registers. 


Use this instruction to load the interrupt descriptor table from the 
memory address operand specified. The interrupt descriptor table is 
six bytes long. Normally, this instruction appears in protected mode 
operating system software only. It does not affect any registers. 


Use this instruction to transfer the global descriptor table to the local 
descriptor table based on the current selector. Normally, this 
instruction appears in protected mode operating system software 
only. It does not affect any registers. 


The load machine status word instruction transfers the value of the 
operand to the machine status word. Normally, this instruction 
appears in operating system software only. It does not affect any 
registers. 


Command 


Load Segment Limit 
(LSL) 


Load Task Register 
(LTR) 


Output String to Port 
(OUTS) 


Output String Byte to 
Port (OUTSB) 


Output String Word 
to Port (OUTSW 


Pop All General 
Registers (POPA) 


Push All General 
Registers (PUSHA) 


Store Global 
Descriptor Table 
Register (SGDT) 


Store Interrupt 
Descriptor Table 
Register (SIDT) 


Store Local Descriptor 
Table Register (SLDT) 


Store Machine Status 
Word (SMSW) 


Store Task Register 
(STR) 


Description 


This instruction loads the descriptor's limit field (if present) into the 
destination operand based on the selector specified in the source 
operand. When successful, the instruction sets ZF; otherwise, it 
clears ZF. 


Use this instruction to load the task register with the value contained 
in the source operand. Normally, this instruction appears in 
operating system software only. It does not affect any registers. 


This instruction allows string output to a port from the source 
operand. Use the DX register to specify the port number and the SI 
register to specify source. The instruction automatically switches 
between word or byte to accommodate the size of the destination 
operand. This instruction does not affect the flags. 


This instruction allows byte output to a port from the source 
operand. Use the DX register to specify the port number and the SI 
register to specify source. This instruction does not affect the flags. 


This instruction allows byte output to a port from the source 
operand. Use the DX register to specify the port number and the SI 
register to specify source. This instruction does not affect the flags. 


POPA removes the general-purpose registers from the stack and 
discards the SP value. It then increments SP by 16. 


PUSHA decrements SP by 2 for each value pushed. It then adds the 
register contents to the location pointed to by the stack pointer (SP) 
The SP value pushed equals SP before instruction execution begins. 


Use this instruction to transfer the six bytes of the global descriptor 
table to the memeory address operand. Normally, this instruction 
appears in protected mode operating system software only. It does 
not affect any registers. 


Use this instruction to transfer the six bytes of the interrupt 
descriptor table to the memeory address operand. Normally, this 
instruction appears in protected mode operating system software 
only. It does not affect any registers. 


Use this instruction to transfer the two bytes of the local descriptor 
table to the memeory address operand. Normally, this instruction 
appears in protected mode operating system software only. It does 
not affect any registers. 


Use this instuction to transfer the machine status word to the 
operand. Normally, this instruction appears in operating system 
software only. 


Use this instuction to transfer the task register contents to the 
operand. Normally, this instruction appears in operating system 
software only. 


Table 2 -3 Continued 


Command Description 


Flag- and processor-control instructions 
Check Array Index 
Against Bounds 
(BOUND) 


Clear the Task 
Switched Flag (CLTS) 


Make Stack Frame for 
Procedure Parameters 
(ENTER) 


High Level Procedure 
Exit (LEAVE) 


Verify a Segment for 
Reading OVERR) 


Verify a Segment for 
Writing OVERW) 


This instruction compares the signed value of the first operand 
against the values pointed to by the second operand. The word at 
the second word is the lower boundary. The word after the second 
word is the upper boundary. This instruction generates an interrupt 
5 whenever the first operand falls outside of either boundary. The 
bound instruction affects none of the flags. 


This instruction (normally used in operating systems) clears the task 
switched flag of the machine register. 


Use this instruction to modify the stack for entry into a high level 
language. The first operand specifies the number of stack storage 
bytes to allocate. The second operand indicates the routine nesting 
level. This instruction does not modify any of the flags. 


Use this instruction when leaving a high-level language procedure to 
reverse the effects of the ENTER instruction. It deallocates all 
variables, then restores SP and BP to their original state. This 
instruction does not affect any flags. 


Use this instruction to determine if the selector specified by the 
operand appears at the current privilege level and is readable. The 
instruction sets ZF for accessable selectors. 


Use this instruction to determine if the selector specified by the 
operand appears at the current privilege level and is writeable. The 
instruction sets ZF for accessable selectors. 


80287 command summary 


Command Description 


Processor-control instruction 
Set protected Mode This instruction sets the 80287 to protected mode operation. 
(FSETPM) 
(80287 Only) 


The 80286 uses a variety of flags that the 8086/8088 processor 
does not provide. Most of these flags are related to the protected 
mode instructions provided by the 80286. In most cases, you will not 
need to use them unless you create an application that handles its 
own protected mode interface. These flags include the following. 


> Nested Task (NT) 


> Input/Output Privilege Level (IOPL) 


> Overflow (OF) 


> Direction (DF) 
> Interrupt (IF) 
> Trap (TF) 
> Sign (SF) 
> Zero (ZF) 


> Auxiliary Carry (AF) 
> Parity (PF) 
> Carry (CF) 


As you can see from Table 2-4, the 80287 provides only one command 
in addition to those provided by the 8087 processor. As with the 8087 
math coprocessor, the 80287 math coprocessor does not use flags. It 
uses a status and control word. The status word indicates the current 
math coprocessor condition. The control word affects math coprocessor 
operation. There is a minor difference between the status and control 
word used by the 8087 and the 80287. The breakdown for both the 
80287 control word and status word is shown here: 


Status Word (bit) 
0 Invalid operation Exception (IE) 
1 Denormalized operation Exception (DE) 
2 Zero Divide Exception (ZE) 
3 Overflow Exception (OE) 
4 Under flow Exception (UE) 
5 Precision Exception (PE) 
7 Error summary status (ES) 
8 Condition code o (CO) 
9 Condition code 1 (C1) 
10 Condition code 2 (C2) 
11-13 Stack Top pointer (ST) 
14 Condition code 3 (C3) 
15 Busy signal (B) 


Controlword (bit) 
0 Invalid operation Exception Mask (IM) 
1 Denormalized operation Exception Mask (DM) 
2 Zero Divide Exception Mask (ZM) 


10-11 


12 
13-15 


Overflow Exception Mask (OM) 
Under flow Exception Mask (UM) 
Precision Exception Mask (PM) 
Precision Control (PC); 00 = 24 bits, 01 = (Reserved), 
10 = 53 bits,11 = 64 bits 
Rounding Control (RC); 00 = Round to Nearest or Even, 
01 = Round Down,10 = Round Up,11 = Truncate 
Infinity Control (IC); 0 = Projective, 1 = Affine 
Reserved 


Table 2-5 


80386 and 80387 
command additions 


The 80386 and 80387 processors provide a lot of capability that the 
average DOS programmer will never use. Not only do they provide a 
much better protected mode interface than the 80286/80287 
processor combination, but a Virtual 86 mode as well. In addition to 
this new mode, both the 80386 and 80387 processors provide a 
wide variety of time-saving commands that you can use to reduce 
your workload. For example, the 80386 chip provides a wide variety 
of new bit-testing instructions. The 80387 chip provides a fully 
functional tangent instruction. It even has a combination sine/cosine 
function. Tables 2-5 and 2-6 list the 80386 processor and 80387 
coprocessor additions respectively. 


80386 command summary 


Command 


Arithmetic instruction 


Convert Doubleword 
to Quadword (CDQ) 


Convert Word to 
Doubleword Extended 
(CWDE) 


Description 


Use this instruction to convert a doubleword value to a quadword 
value. It extends the sign-bit in EAX through EDX. 


Use this instruction to convert a word value to a doubleword value. It 
extends the sign-bit in AX through FAX. 


Bit-manipulation instructions 


Bit scan Forward Use this instruction to scan the bits of the second operand 
(BSF) (beginning at the low-order bit) for any set bits. If the instruction 


Command 


Bit Scan Reverse 
(BSR) 


Bit Test (BT) 


Bit Test and 
Complement (BTC) 


Bit Test and Reset 
(BTR) 


Bit Test and Set 
(BTS) 


Shift Left Double 
Precision (SHLD) 


Shift Right Double 
Precision (SHRD) 


Description 


finds a set bit, it places the bit number in the first operand and clears 
ZF. If it does not find any set bits, it sets ZF and does nothing to the 
first operand. 


Use this instruction to scan the bits of the second operand 
(beginning at the high order bit) for any set bits. If the instruction 
finds a set bit, it places the bit number in the first operand and clears 
ZF. If it does not find any set bits, it sets ZF and does nothing to the 
first operand. 


This instruction uses the value of the second operand as a bit index 
to the first operand. It copies the bit at the indexed position to the 
cany flag. 


This instruction uses the value of the second operand as a bit index 
to the first operand. It copies the complement of the bit at the 
indexed position to the carry flag. 


This instruction uses the value of the second operand as a bit index 
to the first operand. It copies the bit at the indexed position to the 
carry flag and clears the original bit. 


This instruction uses the value of the second operand as a bit index 
to the first operand. It copies the bit at the indexed position to the 
carry flag and sets the original bit. 


The Shift Left Double Precision instruction shifts all bits in the first 
operand left the number of bits specified by the third operand. It 
loses high-order bits and copies low-order bits from the second 
operand starting at the second operand's low-order bit. This 
instruction affects CF, OF, PF, SF, ZF, and AF (undefined). 


The Shift Right Double Precision instruction shifts all bits in the first 
operand right the number of bits specified by the third operand. It 
loses the low-order bits and copies the high-order bits from the 
second operand start and the second operand's high-order bit. This 
instruction affects CF, OF, PF, SF, ZF, and AF (undefined). 


Control-transfer instructions 


Jump if ECX Equals This instruction transfers control to the instruction pointed to by Ip 
Zero (JECXZ) + Displacement when ECx equals o. 


Data-transfer instructions 


Input String 
Doubleword from 
Port (INSD) 


Load the FS Register 
(LFS) 


This instruction allows doubleword input from a port to the 
destination operand. Use the DX register to specify the port number 
and the EDI register to specify destination. This instruction does not 
affect the flags. 


This instruction transfers a 32-bit pointer from the source operand 
(memory only) to the destination operand (offset) and the FS register 
(segment). The destination operand is any 16-bit general purpose 
register. 
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Command 


Load the GS Register 
(LGS) 


Load the SS Register 
(LSS) 


Move with Sign 
Extended (MOVSX) 


Move with Zero 
Extended (MOVZX) 


Output String 
Doubleword to Port 
(OUTSD) 


Pop All General 
Doubleword Registers 
(POPAD) 


Remove Extended 
Flags from Stack 
(POPFD) 


Push All General 
Doubleword Registers 
(PUSHAD) 


Place Extended Flags 
on Stack (PUSHFD) 


Set Byte if Above 
(SETA) 


Set Byte if Above or 
Equal (SETAE) 


Set Byte if Below 
(SETB) 


Set Byte if Below or 


Description 


This instruction transfers a 32-bit pointer from the source operand 
(memory only) to the destination operand (offset) and the GS register 
(segment). The destination operand is any 16-bit general purpose 
register. 


This instruction transfers a 32-bit pointer from the source operand 
(memory only) to the destination operand (offset) and the SS register 
(segment). The destination operand is any 16-bit general purpose 
register. 


Use this instruction to move data from a smaller to larger operand. It 
extends the sign-bit of the second operand to fill the first operand. 


Use this instruction to move data from a smaller to larger operand. It 
clears the bits in the first operand not filled by the second operand. 


This instruction allows doubleword output to a port from the source 
operand. Use the EDX register to specify the port number and the 
ESI register to specify source. This instruction does not affect the 
flags. 


POPAD removes the extended general-purpose registers from the 
stack and discards the ESP value. It then increments ESP by 32. 


POPFD removes the two words pointed to by the stack pointer 
(ESP) and places it in the extended flag register. It then increments 
ESP by 4. 


PUSHAD decrements ESP by 4 for each value pushed. It then adds 
the register contents to the location pointed to by the stack pointer 
(ESP). The ESP value pushed equals ESP before instruction 
execution begins. 


PUSHF decrements ESP by 4. It then adds the extended flag 
register contents to the location pointed to by the stack pointer 
(ESP). 


This instruction checks the status of both CF and ZF. If both flags 
equal 0, then the instruction stores a 1 in the operand; otherwise, it 
stores a 0 in the operand. 


This instruction checks the status of CF. If CF equals 0, then the 
instruction stores a 1 in the operand; otherwise, it stores a 0 in the 
operand. 


This instruction checks the status of CF. If CF equals 1, then the 
instruction stores a 1 in the operand; otherwise, it stores a 0 in the 
operand. 


This instruction checks the status of CF and ZF. If CF or ZF equals 


Command 


Equal (SETBE) 


Set Byte on Carry 
(SETC) 


Set Byte if Equal 
(SETE) 


Set Byte if Greater 
Than (SETG) 


Set Byte if Greater 
Than or Equal 
(SETGE) 


Set Byte if Less Than 
(SETL) 


Set Byte if Less Than 
or Equal (SETLE) 


Set Byte if Not Above 
(SETNA) 


Set Byte if Not Above 
or Equal (SETNAE) 


Set Byte if Not Below 
(SETNB) 


Set Byte if Not Below 
or Equal (SETNBE) 


Set Byte on No Carry 
(SETNC) 


Set Byte if Not Equal 
(SETNE) 


Set Byte if Not 
Greater Than 
(SETNG) 


Description 


1, then the instruction stores a 1 in the operand; otherwise, it stores 
a 0 in the operand. 


This instruction checks the status of CF. If CF equals 1, then the 
instruction stores a 1 in the operand; otherwise, it stores a 0 in the 
operand. 


This instruction checks the status of ZF. If ZF equals 1, then the 
instruction stores a 1 in the operand; otherwise, it stores a 0 in the 
operand. 


This instruction checks the status of ZF, SF and OF. If ZF equals 0 or 
SF equals OF, then the instruction stores a 1 in the operand; 
otherwise, it stores a 0 in the operand. 


This instruction checks the status of SF and OF. If SF equals OF, 
then the instruction stores a 1 in the operand; otherwise, it stores a 
0 in the operand. 


This instruction checks the status of SF and OF. If SF does not equal 
OF, then the instruction stores a 1 in the operand; otherwise, it 
stores a 0 in the operand. 


This instruction checks the status of ZF, SF and OF. If SF does not 
equal OF or ZF equals 1, then the instruction stores a 1 in the 
operand; otherwise, it stores a 0 in the operand. 


This instruction checks the status of CF and ZF. If CF or ZF equals 
1, then the instruction stores a 1 in the operand; otherwise, it stores 
a 0 in the operand. 


This instruction checks the status of CF. If CF equals 1, then the 
instruction stores a 1 in the operand; otherwise, it stores a 0 in the 
operand. 


This instruction checks the status of CF. If CF equals 0, then the 
instruction stores a 1 in the operand; otherwise, it stores a 0 in the 
operand. 


This instruction checks the status of both CF and ZF. If both flags 
equal 0, then the instruction stores a 1 in the operand; otherwise, it 
stores a 0 in the operand. 


This instruction checks the status of CF. If CF equals 0, then the 
instruction stores a 1 in the operand; otherwise, it stores a 0 in the 
operand. 


This instruction checks the status of ZF. If ZF equals 0, then the 
instruction stores a 1 in the operand; otherwise, it stores a 0 in the 
operand. 


This instruction checks the status of ZF, SF and OF. If SF does not 
equal OF or ZF equals 1, then the instruction stores a 1 in the 
operand; otherwise, it stores a 0 in the operand. 
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Command 


Set Byte if Not 
Greater Than or 
Equal (SETNGE) 


Set Byte if Not Less 
Than (SETNL) 


Set Byte if Not Less 
Than or Equal 
(SETNLE) 


Set Byte on No 
Overflow (SETNO) 


Set Byte on No Parity 
(SETNP) 


Set Byte on Not Sign 
(SETNS) 


Set Byte on Not Zero 
(SETNZ) 


Set Byte on Overflow 
(SETO) 


Set Byte on Parity 
(SETP) 


Set Byte on Parity 
Even (SETPE) 


Set Byte on Parity 
Odd (SETPO) 


Set Byte on Sign 
(SETS) 


Set Byte on Zero 
(SETZ) 


Description 


This instruction checks the status of SF and OF. If SF does not equal 
OF, then the instruction stores a 1 in the operand; otherwise, it 
stores a 0 in the operand. 


This instruction checks the status of SF and OF. If SF equals OF, 
then the instruction stores a 1 in the operand; otherwise, it stores a 
0 in the operand. 


This instruction checks the status of ZF, SF and OF. If ZF equals 0 or 
SF equals OF, then the instruction stores a 1 in the operand; 
otherwise, it stores a 0 in the operand. 


This instruction checks the status of OF. If OF equals 0, then the 
instruction stores a 1 in the operand; otherwise, it stores a 0 in the 
operand. 


This instruction checks the status of PF. If PF equals 0, then the 
instruction stores a 1 in the operand; otherwise, it stores a 0 in the 
operand. 


This instruction checks the status of SF. If SF equals 0, then the 
instruction stores a 1 in the operand; otherwise, it stores a 0 in the 
operand. 


This instruction checks the status of ZF. If ZF equals 0, then the 
instruction stores a 1 in the operand; otherwise, it stores a 0 in the 
operand. 


This instruction checks the status of OF. If OF equals 1, then the 
instruction stores a 1 in the operand; otherwise, it stores a 0 in the 
operand. 


This instruction checks the status of PF. If PF equals 1, then the 
instruction stores a 1 in the operand; otherwise, it stores a 0 in the 
operand. 


This instruction checks the status of PF. If PF equals 1, then the 
instruction stores a 1 in the operand; otherwise, it stores a 0 in the 
operand. 


This instruction checks the status of PF. If PF equals 0, then the 
instruction stores a 1 in the operand; otherwise, it stores a 0 in the 
operand. 


This instruction checks the status of SF. If SF equals 1, then the 
instruction stores a 1 in the operand; otherwise, it stores a 0 in the 
operand. 


This instruction checks the status of ZF. If ZF equals 1, then the 
instruction stores a 1 in the operand; otherwise, it stores a 0 in the 
operand. 


Command 
Description 


String-manipulation instructions 


Compare Strings 
Doubleword-by- 
Doubleword (CMPSD) 


Load a Doubleword 
from String into EAX 
(LODSD) 


Move String, 
Doubleword-by- 
Doubleword (MOVSD) 


Scan String for 
Doubleword (SCASD) 


Store Doubleword in 
EAX at String 
(STOSD) 


This instruction changes the value of the AF, CF, OF, PF, SF, and ZF 
flags to show the relationship between two doublewords in a string. 
The results of the comparison do not affect the contents of either 
operand. After comparing the two string words, the instruction 
updates both ESI and EDI to point to the next string element. DF 
controls the direction of comparison. 


Use this instruction to transfer a doubleword from the string pointed 
to by ESI to EAX. The ESI,register automatically advances to the 
next string element in the direction pointed to by the direction flag. 


This instruction moves the doubleword pointed to by ESI to the 
destination pointed to by EDI. Using the REP instruction with this 
instruction, repeats the move the number of times shown in ECX. 
After each move, the instruction advances both ESI and EDI to the 
next position in the direction indicated by DF. 


Use this instruction with any of the repeat instructions to scan 
strings for the value contained in EAX. After each scan, EDI 
advances to point to the next string element. This instruction affects 
AF, CF, OF, PF, SF, and ZF. 


Use this instruction alone or with any repeat instruction to send to 
value in EAX to the string pointed at by EDI. EDI automatically 
advances to the next string location after each store operation. This 
instruction does not affect any flags. 


80387 command summary Table 2-6 


Command 


Arithmetic instruction 


IEEE Partial 
Remainder (FPREM 1) 
(80387 Only) 


Description 


The partial arctangent instruction calculates the modulo of the top 
two stack elements. It performs this by successively subtracting the 
second element from the first. The calculated remainder remains in 
the first element. The instruction affects the CO, C1, C3, UE, DE, 
and IE status bits. 


Comparison instruction 


Unordered compare This instruction converts the operand to an integer (if required) and 
(FUCOM) compares it to the top stack element. It then changes the condition 
(80387 Only) of the status word bits to match the comparison result. The 


difference between this instruction and the standard compare is that 
noncomparable results do not raise the invalid operation exception. 
The status word bits affected include CO, C2, C3, DE, and IE. 


Unordered compare This instruction converts the operand to an integer (if required) and 
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Command 


and Pop (FUCOMP) 
(80387 Only) 


Unordered Compare 
and Pop Twice 
(FUCOMPP) 
(80387 Only) 


Description 


compares it to the top stack element. It then changes the condition 
of the status word bits to match the comparison result and pops the 
stack. The difference between this instruction and the standard 
compare and pop is that noncomparable results do not raise the 
invalid operation exception. The status word bits affected include 
CO, C2, C3, DE, and IE. 


This instruction converts the operand to an integer (if required) and 
compares it to the top stack element. It then changes the condition 
of the status word bits to match the comparison result and pops the 
stack twice. The difference between this instruction and the standard 
compare and pop twice is that noncomparable results do not raise 
the invalid operation exception. The status word bits affected include 
CO, C2, C3, DE, and IE. 


Trancendental instruction 


Cosine (FCOS) 
(80387 Only) 


Sine (FSIN) 
(80387 Only) 


Sine and Cosine 
(FSINCOS) 
(80387 Only) 


This instruction computes Y = COS (a), where a is the top stack 
element. The instruction replaces the top stack element with Y. If a 
exceeds 263, then the instruction sets C2; otherwise, it clears C2. It 
affects the C2, PE, and IE status bits. 


This instruction computes Y = SIN (a), where a is the top stack 
element. The instruction replaces the top stack element with Y. 
exceeds 263, then the instruction sets C2; otherwise, it clears 
affects the C2, PE, and IE status bits. 


This instruction computes Y = SIN (a) and X = COS (a), where a is 
the top stack element. The instruction replaces the top stack 
element with Y, then pushes X. If a exceeds 263, then the 
instruction sets C2; otherwise, it clears C2. It affects the C2, PE, 
and IE status bits. 


The 80386 flag register is 32-bits wide. As a result, it provides you 
with a little more information than the 8088/8086 or 80286 
processors. The 80386 chip does reserve the upper 14 bits of this 
register. The flags used for the various instructions include: 


> Virtual Mode (VM) 


> Resume (R) 


> Nested Task (NT) 


> Input/Output Privilege Level (IOPL) 


> Overflow (OF) 


> Direction (DF) 


> Interrupt (IF) 


> Trap (TF) 


> Sign (SF) 


> Zero (ZF) 


> Auxiliary Carry (AF) 


> Parity (PF) 


> Carry (CF) 


The 80387 math coprocessor uses many of the 8087 commands. It 
does not use any 80287 specific commands. Just like the 8087 and 
80287 math coprocessors, the 80387 math coprocessor does not 
use flags to convey information to the programmer. It uses a status 
and control word. The status word indicates the current math 
coprocessor condition. The control word affects math coprocessor 
operation. The 80387 provides some added functionality in the 
status and control words that the other two math coprocessors do not 
provide. The breakdown for both the control word and status word is 
shown here: 


Status Word (bit) 
0 Invalid operation Exception (IE) 
1 Denormalized operation Exception (DE) 
2 Zero Divide Exception (ZE) 
3 Overflow Exception (OE) 
4 Under flow Exception (UE) 
5 Precision Exception (PE) 
6 Stack Flag (SF); When sF = 1 and co = 0 then stack 


under flow. When SF = 1 and CO = 1 then stack overflow. 


7 Error summary status (ES) 
8 Condition code o (CO) 
9 Condition code 1 (C1) 
10 Condition code 2 (C2) 
11-13 Stack Top pointer (ST) 
14 Condition code 3 (C3) 
15 Busy signal (B) 


Control Word (bit) 
0 Invalid operation Exception Mask (IM) 
1 Denormalized operation Exception Mask (DM) 
2 Zero Divide Exception Mask (ZM) 
3 Overflow Exception Mask (OM) 
4 Underflow Exception Mask (UM) 
5 Precision Exception Mask (PM) 
8-9 Precision control (PC); 00 = 24 bits, 01 = (Reserved),10 


= 53 bits,11 = 64 bits 


10-11 Rounding control (RC); 00 = Round to Nearest or Even, 


01 = Round Down,10 = Round Up,11 = Truncate 


12 Infinity control (IC); 0 = Projective,1 = Affine 
13-15 Reserved 
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80486 command additions 


The 80486 is a lot more than simply a fast 80386 processor with an 
attached 80387 math coprocessor. This chip provides the basis for 
future programming endeavors on the PC. Along with three 
commands unique to its caching capability, the 80486 provides a few 
additional instructions that you can use to make programming a little 
easier. Table 2-7 lists the 80486 processor additions. 


80486 command summary 


Command 


Arithmetic instructions 


Compare and 
Exchange 
(CMPXCHG) 


Exchange and Add 
(RADD) 


Description 


This instruction compares the contents in the destination register to 
the contents of the AL, AX, or EAX register depending on the size 
of the destination. If the size is equal, then the contents of the 
source is copied to the destination. If they are not equal, then the 
destination is copied to the AL, AX, or EAX register. This 
instruction affects the same flags as the CMP instruction: AF, CF, 
OF, PF, SF, and ZF. 


Adds the source and destination operands, then stores the result in 
the destination. The destination is copied to the source before the 
result is stored. This instruction affects the following flags: AF, CF, 
OF, PF, SF, and ZF. 


Command D escription 


Data-transfer instructions 


Byte swap (BSWAP) Use this instruction to convert 80486 register storage to the 


8086/8088 scheme. It swaps the first and the fourth, and the 
second and the third bytes. Instruction does not affect the flags. 


Flag- and processor-control instructions 


Invalidate Data Cache 
(INVD) 


Invalidate Translation 
Lookaside Buffer 
Entry (INVLPG) 


Write Back and 
Invalidate Data Cache 
OvBINVD) 


An OS level instruction that invalidates the data cache without 
writing the contents to memory. Instruction does not affect the flags. 


An OS level instruction that invalidates the Translation Lookaside 
Buffer (TLB) used by the demand paging system of virfual memory 
operation systems. Instruction does not affect the flags. 


An OS level instruction that invalidates the data cache after writing 
the contents to memory. Instruction does not affect the flags. 


The 80486 uses the same flags of the 80386 processor. It also provides 
the full functionality of the 80387 math coprocessor. While the 
80486SX processor does provide all the 80486 instructions, it does not 
provide this math coprocessing capability. You must add an 80487SX 
math coprocessor to gain the full 80486 functionality. The easiest way 
to determine the difference between an 80486 and an 80486SX from a 
programming perspective is to test for the presence of a math 
coprocessor. If your application determines that the host machine 
contains an 80486 processor but no coprocessor, then it really contains 
an 80486SX. If the machine also contains an 80487SX processor, then 
programming is essentially identical to the 80486 chip. 
Pentium processor 
command additions 


The Pentium processor offers many features like the dual execution 
units that this chapter doesn't discuss. It also offers a 128-bit and 
256-bit internal bus, and a 64-bit external bus that speeds program 
execution but really doesn't matter from a programming perspective. 
These are the speed enhancements that receive a lot of media 
attention. The programmer is more interested in the unique 
programmable features that this processor offers. The following 
paragraphs provide you with the full details of these enhancements. 
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There actually are four programming modes for the Pentium 
processor. It supports real, virtual 86, and protected modes like any 
other member of the Intel family. However, the Pentium processor 
also supports a new mode called System Management Mode (SMM). 
This new mode actually started to appear with the 80386SL 
processor. It isn't a new operating mode; the other three modes fulfill 
this function. Essentially, this new mode allows either an application 
program or the operating system to perform power management. For 
example, you could power down the processor during user "think" 
time on a laptop. In most cases, the OS/2 programmer will not need 
to worry about this new mode (unless your company writes power- 
management software), but it is important to realize that the new 
mode does exist. You enter SMM by activating the external interrupt 
pin (SMI#). This switches the CPU to a separate address space and 
saves the entire CPU context. Once you enter SMM, your application 
can execute any required code. The CPU context automatically is 
restored when you exit from SMM using the Resume from System 
Management Mode (RSM) instruction described later. 


Besides these new features, the Pentium processor sports several 
new commands. Table 2-8 provides a complete list of all these new 
commands. Some of these instructions are extensions to the 80486 
command set. For example, the Pentium processor provides a new 
compare and exchange instruction called CMPXCHG8B. Other 
instructions are completely new to the Pentium processor. For example, 
the CPUID instruction allows you to identify the vendor, family, model, 
and stepping of the microprocessor installed in your machine. Still other 
instructions aid the programmer in working with the realities of 
protected mode. For example, the IRETD command supports 32-bit 
operands in place of the 16-bit operands used by the IRET command. 


Pentium processor command summary 


Command 


Arithmetic instructions 


Compare and 
Exchange 8 Bytes 
(CMPXCHG8B) 


Description 


This instruction compares the contents in the destination register to 
the contents of the EDX:EAX register pair. If the two values are 
equal, then the contents of the source is copied to the destination. If 
they are not equal, then the destination is copied to the EDX:EAX 
register pair. This instruction affects the same flags as the CMP 


Command 
Description 


instruction: AF, CF, OF, PF, SF, and ZF. 


Control-transfer instructions 


Return from Interrupt This instruction returns control to a procedure calling an interrupt 
Double (IRETD) after the interrupt completes. The main difference between this 


instruction and the IRET instruction is that IRETD uses a 32-bit 
operand. It pops CS, IP, and all flags. There are three types of 
IRETD instructions versus 4 for IRET. The IRETD instruction does 
not support an interrupt return from real or Virtual 86 mode. 


Flag- and processor-control instructions 


Cpu Identification This instruction provides the vendor, family, model, and stepping of 
(CPUID) the microprocessor installed in the machine. The value in EAX 


determines what information CPUID returns. Placing a 0 in EAX 
returns the highest value understood by the CPUID instruction in 
EAX and a vendor identification string in EBX:EDX:ECX. Placing a 
1 in FAX returns the stepping ID (bits 0 through 3), model (bits 4 
through 7), and family (bits 8 through 11) in EAX. Bits 12 through 
31 of EAX are reserved. EDX contains the feature flags as follows: 
FPU on chip (bit 0), Advanced Features (bits 1 through 6), Machine 
Check Exception toit 7), and CMPXCHG8B Instruction (bit 8). The 
rest of the EDX register bits are reserved. Passing a value higher 
than the highest acceptable value returns an undefined value in the 
EAX, EBX, ECX, and EDX registers. 


Read from Model 
Specific Register 
(RDMSR) 


Resume from System 
Management Mode 
(RSM) 


Use this instruction to retrieve the contents of a model specific register. 
These registers vary by processor type and vendor, so check your 
processor vendor manual for complete details on the types of registers 
available to you. ECX always contains the number of the register that 
you want to check. The EDX:EAX register pair contains the register 
value on return from the call. There are two common register values 
you can retrieve. A value of Ooh in ECX returns the Machine Check 
Address (the address of the eycle causing an exception). A value of 
Olh in ECX returns the Machine Check Type (the eycle type of eycle 
type of cycle causing an exception). Most Intel versions of the Pentium 
processor also return values used to perform cache, TLB, and BTB 
testing and performance monitoring. You must execute this 
instruction from priveledge level 0 or from within real mode. Intel 
reserves ECX values of 03h, OFh, and all values above 13h. 


The RSM instruction returns the processor to its state before 
entering SMM mode. All standard registers are returned to their 
previous state using the contents of the SMM dump. None of the 
model-specific registers are affected by this instruction. Execution 
always continues where it ceased prior to entering SMM. 


The processor does check for invalid state information before it 
turns control over to the application program. If it detects an invalid 
state, it enters a shutdown state. There are three conditions which 
place the processor in an invalid state. 
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Command 


Write to Model 
Specific Register 
WRMSR) 


Description 


• The value stored in the State Dump Base field is not a 


32KB aligned address. 


• Any reserved bit of CR4 is set to 1. 
• CR0 contains any combination of illegal bits. This includes 


(PG=1 and PE=0) or (NW=1 and CD=0). 


Use this instruction to write to a model specific register. There are 
two common register values that you can write. These registers vary 
by processor type and vendor, so check your processor vendor 
manual for complete details on the types of registers available to 
you. ECX always contains the number of the register that you want 
to write to. The EDX:EAX register pair contains the register value 
you want to write. A value of Ooh in ECX writes to the Machine 
Check Address (the address of the cycle causing an exception). A 
value of Olh in ECX write to the Machine Check Type (the cycle 
type of cycle causing an exception). Most lntel versions of the 
Pentium processor also return values used to perform cache, TLB, 
and BTB testing and performance monitoring. You must execute 
this instruction from priveledge level 0 or from within real mode. 
Intel reserves ECX values of 03h, OFh, and all values above 13h. 


Like the 80386 and 80486 chip, the Pentium process provides a 32- 
bit register for flags. The Pentium process supports all the flags of the 
80386 process. It also supports a few additional flags. The following 
list shows all the flags supported by the Pentium processor: 


> ID Flag (ID) 


> Virtual Interrupt Pending (VIP) 


> Virtual Interrupt Flag (VIE) 


> Alignment Check (AC) 


> Virtual Mode (VM) 


> Resume (R) 


> Nested Task (NT) 


> Input/Output Privilege Level (IOPL) 


> Overflow (OF) 


> Direction (DF) 


> Interrupt (IF) 


> Trap (TF) 


> Sign (SF) 


> Zero (ZF) 


> Auxiliary Carry (AF) 


> Parity (PF) 


> Carry (CF) 


Like the 80486, the Pentium process includes the equivalent of an 
80387 math coprocessor infernally. This includes both the control 
and status word used by that coprocessor. There is no difference 
between programming the 80387 math coprocessor and the Pentium 
processor. The only differences are internal design features that 
speed math computation processing. These features are invisible to 
the programmer. 


Conclusion 


This chapter provided you with all that you need to know about the 
``brain" of your computer-the processor. Each section described one 


member of the Intel family in detail. As applications continue to grow 
in complexity, you might find that you need to use the increased 
capacity of the higher-level processor in lieu of compatibility with 
older processor versions. This chapter provides you with a stepped 
view of what each processor can provide in addition to the base 
instruction set provided by the 8086/8088 processor and 8087 math 
coprocessor. 
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t doesn't matter how much work your application can perform if 
it can't interact with the user. This usually means 


that you must provide some type of visual feedback as a minimum. 
Today's GUI environment provides a lot more in the way of 
programmer's tools to create displays that are both functional and 
visually appealing. This chapter describes the video application 
programming interface (API) provided by OS/2. This chapter views 
programming from the business application viewpoint. Because 
OS/2 does not allow direct hardware manipulation by ``ring 3" 
applications, the programmer must use the tools supplied by the 
operating system. (You can always choose to create your own device 
drivers and DLLs to perform any required work.) 


The example programs in this chapter also assume that you want to 
program for the Presentation Manager. While most of the VIO 
functions work only in a full-screen character-mode OS/2 session, 
you can even use some of them within the Presentation Manager. 
(The text will note whether you can use a particular call for 
character-and graphics-mode applications.) The main area 
addressed by this chapter is the drawing functions OS/2 provides. 
The programmer needs to know how to use this capability to 
program in OS/2. 


Drawing 


Whether or not you consider yourself an artist, almost every GUI 
program requires some type of drawing. Even graphs and charts are 
considered drawing by most people. Of course, every program 
includes an icon and other interesting graphics as well. The following 
paragraphs describe the commands that you can use for drawing 
within OS/2. 


VIO functions 


There are many video input/output (VIO) functions provided in the 
OS/2 API. Most of these functions affect the way that OS/2 sees 
your application screen space. For example, VioEndpopup ends a 
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pop-up screen displayed over your standard screen. Version 1.1 of 
OS/2 provided many VIO functions in addition to the ones that were 
documented for Version 1.3. These functions appear in Table 3-1. 
There is no guarantee that they will work in the OS/2 2.x 
environment or that IBM will support them in the future. 


AVIO function listing 


Function 


Ushort VioAssociate 
(hDC, hvps) 


Ushort 
ViocreateLogFont 
(pFAttr, lcID, 
pstr8Name, hvps) 


Description 


The VioAssociate function associates an AVIO presentation space 
with a device context. hDC contains a device context handle. hvps 
contains a presentation space handle. 


You need to make subsequent calls to Vioshowps or VioshowBuf 
functions to direct output to this device context. You can use only 
screen devices as the device contents for the presentation space. 
Any previous associations are disassociated when you use this 
function. In addition, using a Null device context disassociates the 
presentation space with the current device context. You must call 
Viocreateps prior to using this function. Any return value other 
than 0 indicates an error condition. 


The ViocreateLogFont function creates a logical font for the 
specified presentation space. pFAttr contains a point to a font 
attribute table. ICID contains the local font identifier. pstr8Name 
contains a pointer to a descriptive name for the logical font. 
hvps contains a presentation space handle. 


A logical font contains a complete description of all the attributes 
required to create the font itself . When it comes time to use the font, 
OS/2 selects the one that most closely matches the font description. 
Setting the szFaceName field to Null and all other attributes (except 
code page) to 0 in the FAttr structure selects the system default font. 
Any return value other than 0 indicates an error condition. The FAttr 
structure contains the following elements: 
Offset Length Description 


Ooh 2 Length of structure 


02h 2 Font characteristics: italic (bit o), underline (bit 


1), reverse (bit 2), outline (bit 3), and strikeout 
(bit 4). All other bits are reserved. 


4 Match number from vioQueryFonts call (use o 


to use the best match). 


32 ASCIIz typeface name 


2 Font registry number 


2 Code page identifier 


Function 


Ushort Viocreateps 
(phvps, cBows, 
ccolumns, fFormat, 
cAttrBytes, hvps) 


Ushort 
VioDeletesetld 
(lcID, hvps) 


Ushort VioDestroyps 
(hvps) 


Ushort 
VioGetDevicecellsize 
(pcBOws, 
pccolumns, hvps) 


Description 
Offset Length Description 


4 Maximum baseline extent 
4 Average character width 


2 Width class 


2 Weight class 
2 Kerning and proportional space flags: reserved 


(bit 0), nonproportional font (bit 1), kernable 
font (bit 2, always set to 0), reserved (bits 3 
through 15). 


3Ch 2 Font quality: default (bit o, always set to 1), 


draft (bit 1, always set to 0), proof (bit 2, always 
set to 0), reserved (bits 3 through 15) 


3Eh 2 Reserved, always set to o. 


The Viocreateps functions creates an AVIO presentation space. 
phvps contains a pointer to a variable used to hold the presentation 
space handle. cBows contains the height of the presentation space. 
ccolumns contains the width of the presentation space. fFormat 
contains attribute byte format flags. The only value that you 
currently can use for this entry is 0. cAttrBytes contains the number 
of attribute bytes per character cell. Use a value of 1 for the 
FORMAT_CGA setting or 3 for the FORMAT_4BYTE setting. hvps 
contains a presentation space handle (always set this entry to 0). 
The size of the presentation space (cRows x ccolumns x (cAttrBytes 
+ 1)) must not exceed 32K. The FORMAT_CGA setting include the 
following information: character code (byte 0) and text mode 
attribute (byte 1). The FORMAT_4BYTE setting includes the 
following information: character code (byte 0), foreground/ 
background colors (byte 1), underline/reverse/blink/font ID (byte 2), 
and user information (byte 3). Any return value other than 0 
indicates an error condition. 
The VioDeletesetld function releases a logical font identifier 
assigned using the ViocreateFont function. ICI D contains the local 
font identifier. hvps contains a presentation space handle. You can 
release all font identifiers by using a lcID value of -1. Any return 
value other than 0 indicates an error condition. 
The VioDestroyps function releases the specified AVIO presentation 
space. hvps contains a presentation space handle. You must obtain 
this handle using the Viocreateps function. Any return value other 
than 0 indicates an error condition. 
The VioGetDevicecellsize retrieves the size of the current device 
cell. pcBows contains a pointer to a variable containing the cell 
height. pccolumns contains a pointer to a variable containing the 
cell width. hvps contains a presentation space handle. Any return 
value other than 0 indicates an error condition. 


Table 3-1 Continued 


Function 


Ushort VioGetorg 
(psBOw, 
pscolumn, hvps) 


Ushort 
VioQueryFonts 
(pcbMetrics, PFM, 
cbMetrics, 
pcFonts, 
pszFacename, 
floptions, hvps) 


Description 


The VioGetorg function retrieves the origin of the AVIO 
presentation space. psBow contains a pointer to a variable 
containing the row number of the upper-left corner of the window. 
pccolumns contains a pointer to a variable containing the column 
number of the upper-left corner of the window. hvps contains a 
presentation space handle. Any return value other than 0 indicates 
an error condition. 


The VioQueryFonts function retrieves a font metric structure 
containing the characteristics of one or more fonts. pcbMetrics 
contains a pointer to a variable holding the structure length. 
PFM contains a pointer to the front metric structure. cb Metrics 
contains the structure length. pcFonts contains a pointer to a 
variable holding the number of fonts. pszFacename contains a 
pointer to an ASCIIZ string holding the face name string. floptions 
contains the enumeration options. hvps contains a presentation 
space handle. 


The size of PFM determines the absolute number of font metric 
structures that OS/2 returns. OS/2 fills the structure until it either 
runs out of fonts that match the string in pszFacename or room in 
the structure. You can use the ViocreateLogFont function to select 
any of the fonts returned in the structure. Specifying a value of 0 in 
the pcFonts parameter returns the number of available fonts for the 
specified face name. Any return value other than 0 indicates an error 
condition or the number of fonts not retrieved. The font metrics 
structure uses the following format: 
Offset Length Description 


Ooh 32 Family name of the font. This is a null- 


terminated string up to 31 characters long. For 
the purposes of this table, I assume a 
31-character length. 


20h 32 Typeface name of the font. This is a null- 


terminated string up to 31 characters long. For 
the purposes of this table, I assume a 
31-character length. 


2 Font registry number (always set to o) 


2 Code page that application should use with the 


font (set to 850 in most cases). 


4 Average height of uppercase characters. 


4 Average height of lowercase characters. 


4 Maximum height of any character (ascender). 


Function 
Description 
Offset Length 
50h4 
54h4 
58h4 
5Ch4 


60h4 


78h 


Description 


Maximum depth of any character (descender). 


Maximum height of any lowercase character. 


Maximum depth of any lowercase character. 


Amount of space reserved at the top of each 
character cell for accent marks. 


Amount of space that should appear between 
adjacent rows of text. 


4 Average character width for each character in 


the font. 


4 Maximum increment between characters in the font. 


4 Width of an uppercase M. 


4 Maximum ascender and descender values. 


2 Stroke angle in degrees and minutes. Bits o 


through 8 contain the degrees, bits 9 through 
14 contain the minutes, and bits 15 and 16 are 
reserved. Normal fonts are always zero; italic 
fonts are always nonzero. 


2 Angle in degrees and minutes of the next 


character in a string (baseline). Bits 0 through 8 
contain the degrees, bits 9 through 14 contain 
the minutes, and bits 15 and 16 are reserved. 
Swiss fonts are always 0, while Hebrew fonts 
are always 180. 


Angle of the baseline rotation used for aligning 
characters in a string. The font designer 
determines this value. Bits 0 through 8 contain 
the degrees, bits 9 through 14 contain the 
minutes, and bits 15 and 16 are reserved. 


7Ah 2 Thickness of the strokes that form the 


character. The following values determine 
stroke width: ultra-light (1), extra-light (2), light 
(3), semi-light (4), medium (5), semi-bold (6), 
bold (7), extra bold (8), and ultra-bold (9). 


7Ch2 
Font aspect ratio when compared to a standard 
font in this family. The following nine values 
determine the font aspect ratio: ultra-condensed 
(1), extra-condensed (2), condensed (3), semi- 
condensed (4), normal (5), semi-expanded (6), 
expanded (7), extra-expanded (8), and ultra- 
expanded (9). 
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-____---_-_-:--- 


Function D es cription 


Offset Length 
7Eh2 


94h2 


Description 


Horizontal resolution of the device for which 
the font originally was designed in pels. 


Vertical resolution of the device for which the 
font originally was designed in pels. 


Code point for the first character in the font. 


Code point for the last character in the font. 


Code point for the default character in the font. 
This is the font that OS/2 uses when an 
application requests a font outside the normal 
range of font's code page. 


Code point for the space character in the font. 


Nominal font height in decipoints (1/2o of an inch). 


Minimum font height in decipoints. 


Maximum font height in decipoints. 


Font type including zero or more of the 
following values : FM_TYPE_FIXED, 
FM_TYPE_LICENSED , FM_TIME_KERNING , 
FM_TYPE_DBCS , FM_rvpE_MBCS, and 
FM mE 64K. 


Font definition including zero or more of the 
following values: FN_DEFN_OUTLINE and 
FN DEFN GENERIC. 


Character drawing specification including zero or 
more of the following values: FM_SEL_ITALIC, 
FM_SEL_UNDERSCORE , FM_SEL_NEGATIVE , 
FM_SEL_OUTIJNE, FM_SEL_STRIKEOUT, and 
FM SEL BOLD. 


If this field contains the value FM_CAP_NOMIX, 
you cannot mix it with graphics; otherwise, you 
can use the font with graphics. 


Horizontal size of font subscripts. 


Vertical size of font subscripts. 


Horizontal offset of font subscripts from the left 
edge of the character cell. 


Vertical offset of the font subscripts from the 
character cell baseline. 


Function 


Ushort 
VioQuerysetlds 
(palcIDs, 
pachNames, 
palTypes, csets, 
hvps) 


Ushort 
ViosetDevicecellsize 
(cBows, ccolumns, 
hvps) 
Ushort Viosetorg 
(sBow, scolumns, 
hvps) 


Ushort Vioshowps 
(cBows, ccolumns, 
off , hvps) 


Description 
Offset I.ength 


104h 4 


108h 4 
loch 4 


110h 4 


126h 2 
128h 4 


Description 


Horizontal size of font superscripts. 


Vertical size of font superscripts. 


Horizontal offset of font superscripts from the left 
edge of the character cell. 


Vertical offset of the font superscripts from the 
character cell baseline. 


Width of the font underscore. 


Distance from font baseline to underscore. 


Width of the font overstrike. 


Distance from font baseline to overstrike. 


Number of kerning pairs for the font in the 
kerning pair table. 


Font family class and subclass. 


Contains a long integer value that gets copied 
to the FAttrs structure when the 
GpicreateLogFont function is called. The 
system selects a font that contains the metrics 
associated with the field. 


The VioQuerysetlds function retrieves information about all 
available logical fonts. palcIDs contains a pointer to an array of 
local identifiers for fonts. pachNames contains a pointer 
to an array of font names. palTypes contains a pointer to an 
array of object types. csets contains the number of local identifiers 
currently in use. hvps contains a presentation space handle. Any 
return value other than 0 indicates an error condition. 


The ViosetDevicecellsize sets the size of the current device cell. 
cBows contains the cell height in pels. ccolumns contains the cell 
width in pels. hvps contains a presentation space handle. Any return 
value other than 0 indicates an error condition. 
The Viosetorg function sets the origin of the AVIO presentation space. 
sBow contains the row number of the upper-left corner of the 
window. ccolumns contains the column number of the upper-left 
corner of the window. hvps contains a presentation space handle. 
Any return value other than 0 indicates an error condition. 
The Vioshowps updates the display by copying all the changes in 
the specified window to the display. cBows contains the window 
height in pels. ccolumns contains the width in pels. off contains the 
upper left corner of the window. This position is relative to the first 
character in the AVIO presentation space. hvps contains a 
presentation space handle. Any return value other than 0 indicates 
an error condition. 


The Borland compiler does provide access to these functions through 
the PMAVIO.H include file. You might need to check the include files 
for your compiler to find references to these functions because most 
vendors do not document them. In some cases, the vendor uses a new 
name for the function. Fortunately, most vendors include a file with 
#defines that allow you to use the original names. 


The remaining VIO functions do appear in OS/2 version 1.3 and 
above in their original state. Many of these functions have 
limitations regarding the Presentation Manager. There is at least 
one of the following three classifications assigned to each function. 
You can use FAPI functions in a family API application; a family 
API application runs equally well in DOS or OS/2. Presentation 
Manager will not allow you to use a XPM function within an 
application designed for that environment. However, you can use 
these functions in a windowed OS/2 character-mode session. A 
final restriction is that XWPM functions cannot appear in windowed 
OS/2 character-mode sessions; you must restrict their use to full 
screen sessions only. 


The Borland compiler provides access to these functions through the 
BSESUB.H include file. You might need to check the include files for 
your compiler to find references to these functions, because most 
vendors do not document them. In some cases, the vendor uses a new 
name for the function. Fortunately, most vendors include a file with 
#defines that allow you to use the original names. 


Table 3-2 contains a complete list of these functions. Remember 
that these are the functions supported by OS/2 versions 1.3 and 
above in their original version 1.1 state. The table includes the 
parameters for calling the functions, any restrictions, a complete 
description of the function, and a full listing of error codes that the 
function returns. It does not include any compiler specific calls like 
the ViocheckcharType function supported by the Borland 
compiler. 


VIo function listing Table 3-2 


Function 


XWPM 
Ushort 
VioDeBegister 
(Void) 


XPM 
Ushort VioEndpopup 
(hvio) 


XPM 
Ushort VioGetAnsi 
(pfANsl, hvio) 


EAPI 
Ushort VioGetBuf 
(pulLVB, pcbLVB, 
hvio) 


Description 


The VioDeRegister function deregisters a video subsystem previously 
registered within a session (all the processes in the current screen 
group). VioDeRegister must be issued by the same process that 
issued the previous VioRegister. After VioDeRegister is issued, 
subsequent video calls are processed by the Base Video Subsystem. 
VioDeRegister returns one of the following values: 


0 NO ERROR 


404 EREOR VIO DEREGISTER 
430 ERROR-VIO-ILLEGAL DURING POPUP 
465 ERROR-VIO-DETACHED 
494 ERROR-VIO-EXTENDED SG 


The VioEndpopup function closes a pop-up screen and restores the 
video buffer to its previous state. hvio contains a handle to the video 
buffer. Only the process that issued a Viopopup can call this function 
to end it. Always use a handle value of 0 for Presentation 
Manager applications. 
There are some instances where this call will not restore the screen 
fully. For example, if your application modified the contents of any 
of the display adapter registers, it would have to restore the state of these 
registers before the VioEndpopup function executes. Use the 
VioModewait function to request that OS/2 notify you of the change 
in video conditions. VioEndpopup returns one of the following values: 


0 NO ERROR 


405 EREOR VIO NO POPUP 
436 ERROR-VIO-INVALID HANDLE 
The VioGetAnsi function retrieves the state of the ANSI flag. This 
determines whether OS/2 can process ANSI escape sequences. 
pfANsl is a pointer to a variable which receives the ANSI flag. 
hvio contains a handle to the video buffer. Always use a handle 
value of 0 for Presentation Manager applications. Character 
mode applications must provide a handle obtained using the 
Viocreateps function. VioGetAnsi returns one of the following values: 


0 NO ERROR 


436 ERfroR vlo INVALID HANDLE 
465 ERROR-VIO-DETACH-ED 


The VioGetBuf function retrieves the address of a logical video 
buffer (IJVB). pulLVB contains a pointer to a variable that holds 
the address of the IJVB. Never assume the offset portion of this 
variable is 0. pcbLVB contains a pointer to a variable which holds the 
length of the IJVB. The buffer length equals Rows x Columns x Cell 
Size. hvio contains a handle to the video buffer. 


A process can modify the IJVB at any time-even while it executes 
in the background. In most cases, the IJVB and physical display 


Table 3-2 Continued 


Function 


FAPI 
Ushort VioGetconfig 
(usconfiguration, 
pvioln, hvio) 


Description 


buffer (PDB) are the same when the application is in the foreground. 
OS/2 automatically updates the PDB when the application switches 
to the foreground. This changes if you issue a VioGetphysBuf call. 
OS/2 stops updating the PDB even if the application is in the 
foreground. The application can display the contents of the IJVB 
using the VioshowBuf function. You can use the VioGetMode 
function to determine the size of the buffer. Issuing a ViosetMode 
call changes the size of the logical buffer to match the dimensions of 
the new mode. VioGetAnsi returns one of the following values: 


0 NO ERROR 


355 ERkoR VIO MODE 
430 ERROR-VIO-ILLEGAL DURING POPUP 
436 ERROR-VIO-INVALID -HANDLE- 
465 ERROR-VIO-DETACH-ED 


The VioGetconfig function returns the video display configuration 
including: display adapter type, display type, and amount of video 
memory. usconfiguration determines which display configuration 
the call retrieves. You can use any of the following values: 0 for 
current, 1 for primary, and 2 for secondary. pvioln contains the 
address of the display configuration structure. hvio contains a handle 
to the video buffer. The display configuration structure consists of 
the following elements: 
Offset Length Description 


Ooh 2 Length of structure. 
02h 2 Display adapter type including: 0 monochrome, 


1 CGA, 2 EGA, 3 VGA, 4-6 reserved, 7 
8514/A, 8 PS/2 Image Adapter/A, or 9 XGA. 


04h 
2 Display type including: 0 monochrome,1 CGA, 


2 EGA, 3 PS/2 monochrome (8503), 4 PS/2 
color (8512 and 8513), 5-8 reserved, 9 PS/2 
color (8514),10 IBM plasma display panel,11 
monochrome (8507 and 8604), 12 PS/2 color, 
or 13 reserved. 


4 Amount of display adapter memory in bytes. 
2 The number of the display adapter used to used 


to derive this information. It comes from the 
video subsystem rather than the Base Video 
Handler (HVH). 


2 Reserved 


2 Flags 
0 Power up display configuration 


1-15 Reserved 


Function 
Description 
Offset Length 
10h4 


14h4 


18h4 


1Ch2 


1Eh2 


20h2 


28h 


Description 


The BVH buffer size in bytes. This is the 
number of bytes used to store the full hardware 
state excluding the physical display buffer. 
The maximum BVH buffer size in bytes. This is 
the amount of memory required to store the full 
physical display buffer. 
The pop-up BVH buffer size in bytes. This is 
the amount of memory required to store the 
area of the physical display buffer overlaid by a 
POP-uP. 
This entry provides an offset into the 
configuration data structure that contains a 
description of what other display adapters this 
adapter emulates. Each emulation entry 
contains the data shown in the following 
paragraphs. 
Contains the a count of the number of words to 
follow. 
Display adapters emulated by this display 
adapter. Each bit represents a different display 
adapter type. 


0 Monochrome 
1CGA 
2EGA 
3 VGA or ps/2 Display Adapter 
4-6 Reserved 
7 8514/A 
8 PS/2 Image Adapter/A 
9XGA 


10-15 Reserved 
Reserved 
Reserved 
This entry provides an offset into the 
configuration data structure that contains a 
description of what other displays this display 
emulates. Each emulation entry contains the 
data shown in the following paragraphs. 
Displays emulated by this display. Each bit 
represents a different display type. 


0 5151 Monochrome 
1 5153 CGA 
2 5154 EGA 
3 8503 Monochrome 


Table 3 -2 Continued 


Function 


XPM 
Ushort VioGetcp 
(usBeserved, 
plDCodepage, hvio) 


FAPI 
Ushort 
VioGetcurpos 
(pusF3ow, 
puscolumn, hvio) 


FAPI 
Ushort 
VioGetcurType 
(pviocursorlnfo 
hvio) 


Description 
Offset Length Description 


4 8512 or 8513 Color 
5-8 Reserved 
9 8514 Color 
10 IBM plasma Display panel 
11 8507 and 8604 Monochrome 
12 8515 Color 
13-15 Reserved 


2Ah 2 Reserved 
2 Ch 2 Reserved 


VioGetconfig returns one of the following values. 


0 NO ERROR 


421 ERROR VIO INVALID PARMS 
436 ERROR-VIO-INVALID-HANDLE 
438 ERROR-VIO-INVALID-LENGTH 
465 ERROR-VIO-DETACH-ED 
The VioGetcp function returns the current code page used to 
display text data. usBeserved contains a value of zero. 
plDCodepage contains a pointer to a word used to store the code 
page number. A return value of 0 indicates that the current code 
page is the ROM font provided by the display adapter. hvio contains 
a handle to the video buffer. VioGetcp returns one of the following 
values: 


0 NO ERROR 


355 ERffoR VIO MODE 
436 ERROR-VIO-INVALID HANDLE 
465 ERROR-VIO-DETACH-ED 
468 ERROR-VIO-USER FONT 
The VioGetcurpos function returns the current row and column 
coordinates of the cursor. pusBow contains a pointer to the row 
variable. puscolumn contains a pointer to the column variable. 
A return value of 0 in both variables indicates the cursor is in the 
upper left corner of the display. hvio contains a handle to the video 
buffer. VioGetcurpos returns one of the following values: 


0 NO ERROR 


355 ERROR VIO MODE 
436 ERROR-VIO-INVALID HANDLE 
465 ERROR-VIO-DETACH-ED 
The VioGetcurType function returns the cursor type. pviocursorl nfo 
contains a pointer to a structure containing the cursor information. 
hvio contains a handle to the video buffer. The pviocursorlnfo data 
structure consists of the following elements: 


Function 


FAPI XWPM 
Ushort VioGetFont 
(pviofi, hvio) 


Description 


Offset I+ength Description 
00h2 


02h2 


04h2 


06h2 


The top horizontal scan line of the cursor within 
a character cell. 


The bottom horizontal scan line of the cursor 
within a character cell. 


Cursor Width. In character mode, the cursor 
width equals the number of character columns 
on the display. In graphics mode, the cursor 
width is measured in pels. 


Cursor Attribute. A value of -1 indicates a 
hidden cursor. Any other value in text mode 
indicates that the user can see the cursor. In 
graphics mode, any other number indicates the 
color of the cursor. 


VioGetcurType returns one of the following values: 


0 NO ERROR 


355 ERfroR vlo MODE 
436 ERROR-VIO-INVALID HANDLE 
465 ERROR-VIO-DETACH-ED 
468 ERROR-VIO-USER FONT 


The VioGetFont function returns a font table for the font in use or 
the one you specify. pviof i contains a pointer to a table used 
to store the font data. hvio contains a handle to the video buffer. The 
pviofi data structure consists of the following elements: 
Offset Length Description 


Ooh 2 Length of structure. 


02h 2 Request Type. A value of o gets the current 


RAM font for EGA, VGA, or SVGA display 
adapters. A value of 1 gets the ROM font for 
CGA, EGA, VGA, or SVGA display adapters. 


Och 


2 Pel columns in character cell. 


2 Pel rows in character cell. 


4 Pointer to a block of storage space in the 


application data area. This area contains the 
font table when this function returns. 


Length of the caller-supplied font table storage 
area in bytes. 


VioGetFont returns one of the following values: 


0 NO ERROR 
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Function D es cription 


355 ERROR VIO MODE 
421 ERROR-VIO-INVALID PARMS 
438 ERROR-VIO-INVALID-LENGTH 
465 ERROR-VIO-DETACH-ED 
467 ERROR-VIO-FONT 
494 ERROR-VIO-EXTENDED SG 


FApl XPM The vioGetMode function returns the current display mode 
Ushort vioGetMode information. pvioModelnfo contains a pointer to a table used to 
(pvioModelnfo, hvio) store the mode data. hvio contains a handle to the video buffer. The 


pvioModel nfo data structure consists of the following elements: 
Offset Length Description 


Ooh 2 Length of structure. The value that you supply 


controls the amount of display mode data 
returned. The minimum value is 2, and the 
maximum is 34. A length of 2 returns the 
maximum structure size required to return all 
mode data. 


02h1 


03h1 


Mode characteristics bit mask 


0 0 = Monochrome compatible mode 


1 - Other 


1 0 = Text mode 


1 = Graphics mode 


2 0 = Enable color burst 


1 = Disable color burst 


3 0 = VGA compatible modes o-13h 


1 = Native mode 


4-7 Reserved 


Number of colors defined as a power of two: 


0 = monochrome 
1 = 2 colors 
2 - 4 colors 
4 = 16 colors 
8 = 256 colors 


2 Number of text columns. 


2 Number of text rows. 


2 Horizontal resolution in pels. 


2 Vertical resolution in pels. 


1 Format of the attributes. 


1 Number of attributes in a character cell. 


Function 


FAPI XWPM 
Ushort 
VioGetphysBuf 
(pviophysBuf, 
usBeserved) 


Description 
Offset ltength 
OEh4 


12h4 
16h4 


1Ah4 


1Dh4 


Description 


32-bit address of the physical display buffer for 
this mode. 


Length of the physical display buffer for this mode. 


Size of the buffer required for a full save of the 
physical display buffer for this mode. 
Size of the buffer required for a partial (pop-up) 
save of the physical display buffer for this mode. 
Far address to the extended mode data 
structure. The format of this structure varies by 
display adapter and is unknown to OS/2. 


VioGetMode returns one of the following values: 


0 NO ERROR 


436 EREOR VIO INVALID HANDLE 
438 ERROR-VIO-INVALID-LENGTH 
465 ERROR-VIO-DETACH-ED 
494 ERROR-VIO-EXTENDED SG 
The VioGetpkysBuf function obtains an address to the physical display 
buffer. pvioModelnfo contains a pointer to a table used to store the 
pkysical display buffer data. usBeserved contains a value of zero. 
The pvioModel nfo data structure consists of the following elements: 


Offset Length Description 


Ooh 4 Pointer to the 32-bit start address of the 


physical display buffer. This address range must 
fall between A0000h and BFFFFh, inclusive. 
If the display buffer length is 0, then 
VioGetphysBuf returns one selector 
corresponding to the address of the current 
display mode. 


04h 4 Display buffer length. 


08h-XX 2 per Physical display buffer selector list. Each 


selector selector points to one 64K block of the 


physical display buffer. The last selector 
points to either a whole or partial 64K block 
(depending on the size of the buffer). 


XX+2 2 Length of the physical buffer in bytes. 


XX+4-YY 2 per Eachselectorpointstoone 64Kblockof 


selector the physical video buffer. 


Issuing a VioGetphysBuf after a VioGetBuf call sends all Viowrtxx 
calls to the physical display buffer instead of the IJVB. An application 
can only issue this call while operating in the foreground. It must 
issue a VioscrLock call prior to using the physical display buffer. 
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Function 


EAPI XWPM 
Ushort VioGetstate 
(pstate, hvio) 


Description 


VioGetphysBuf returns one of the following values: 


0 NO ERROR 


350 ERkoR VIO PTR 
429 ERROR-VIO-IN BG 
430 ERROR-VIO-ILLEGAL DURING POPUP 
436 ERROR-VIO-INVALID -HANDLE- 
465 ERROR-VIO-DETACH-ED 
494 ERROR-VIO-EXTENDED SG 


The VioGetstate function returns one of several types of information 
about the video adapter. This includes the various types of register 
information. pstate contains a pointer to a structure. There are six 
different structures; each one corresponds to a particular structure. 
The structure types include: get palette registers (0), get overscan 
color (1), get blink/background intensity switch (2), get color registers 
(3), get the scan line for underlining (5), and get target display 
configuration (6). Types 4 and 7 currently are reserved. hvio contains 
a handle to the video buffer. The pstate data structure consists of the 
following elements (depending on the type of request you make): 
Offset Ilength Description 


Get palette registers (Viopalstate) 


00h 2 Length of structure. (Maximum length of 38 


allowed.) 


02h 2 Set to o for palette registers. 


04h-XX 2 per Input only. One entry for each palette register. 


entry The length of the structure determines the 


number of palette registers returned. The 
palette registers are numbered 0 through 15. 


04h-XX 2 per Output only. One entry for each palette register 


entry that youwish to set. You may specify a 


maximum of 16 register entries. 


Get ouerscan color (Vioouerscan) 


00h 2 Length of structure. The only valid value is 6. 


02h 2 Set to 1 for overscan (border) color. 


04h 2 Color value 


Get blink/background intensity switch (Violntensity) 


00h 2 Length of structure. The only valid value is 6. 


02h 2 Set to 2 for blink/background intensify switch. 


04h 2 Use the following values to set the switch: 


Function 
Description 
Offset Length Description 


0 = Blinking colors enabled 
1 = High Intensity colors enabled 


Get color registers (ViocolorReg) 
00h2 
02h2 
04h2 


06h2 
08h4 


Length of structure. The only valid value is 12. 
Set to 3 for color registers. 


Value of the first color register value to retrieve 
(0-255). The color registers are returned in 
sequential order. 
Number of color registers that you want 
returned (1-256). 
Pointer to a data area to use to store the 
register values. Multiply the number of registers 
that you want to retrieve by 3 bytes to 
determine the size of the data area needed. 
Each register entry contains one byte each of 
color information in the following order: red, 
green, and blue. 


Get the scan line for underlining (ViosetulineLoc) 
00h2 
02h2 


04h2 


Length of structure. The only valid value is 6. 
Set to 5 to get the scan line for underlining. 
You can only use this feature if the foreground 
color is 1 or 9. You cannot use this value in a 
family API application. 
Value of the scan line in the range 0 to 31. 
Setting this entry to 32 disables underlining. 


Get target display configuration (ViosetTarget) 


00h 2 Length of structure. The only valid value is 6. 
02h 2 Set to 6 to get the display configuration that 


you want to select as the target for the next 
ViosetMode function call. You cannot use this 
value in a family API application. 


04h 2 Configuration value: 0 for default selection, 


1 for primary, or 2 for secondary. 


VioGetstate returns one of the following values: 


0 NO ERROR 


355 ERROR VIO MODE 
421 ERROR-VIO-INVALID PARMS 
436 ERROR-VIO-INVALID-HANDLE 
438 ERROFl-VIO-INVALID-LENGTH 
465 ERROR-VIO-DETACH-ED 
494 ERROR-VIO-EXTENDED SG 


Table 3 -2 Continued 


Function 


XWPM 
Ushort 
VioGlobalBeg 
(pszModName, 
pszEntryName, 
flFunl , flFun2, 
usBeturn) 


Description 


The VioGlobalReg function allows an application to receive 
notification of the completion of any VIO call by any full-screen 
session. pszModName contains the address of a one to eight 
character ASCIIZ string that identifies the subsystem. You must use a 
DLL for the subsystem name. Do not include the DLL extension 
as part of the name. pszEntryName contains an address to a one to 
thirty-two character ASCIIZ string that identifies the entry point 
within the DLL. This is the routine that receives control when 
another thread executes a registered VIO function in a full-screen 
session. flFunl contains a bit mask that identifies the video functions 
that you want registered. Push the high-order 16 bits onto the stack 
first, then the low-order 16 bits. Each bit registers one or more of 
the following functions: VioGetcurpos (0), VioGetcurType (1), 
VioGetMode (2), VioGetBuf (3), VioGetphysBuf (4), Viosetcurpos 
(5), ViosetcurType (6), ViosetMode (7), VioshowBuf (8), 
VioReaccharstr (9), VioReadcellstr (10), ViowrtNchar (11), 
ViowrtNAttr (12), ViowrtNcell (13), ViowrtlTY (14), 
Viowrtcharstr (15), ViowrtcharstrAtt (16), Viowrtcellstr (17), 
Vioscrollup (18), VioscrollDn (19), VioscrollLf (20), VioscrollRt 
(21), ViosetAnsi (22), VioGetAnsi (23), Vioprtsc (24), 
VioscrLock (25), Vioscrunlock (26), ViosavRedrawwait (27), 
ViosavRedrawundo (28), Viopopup (29), VioEndpopup (30), and 
VioprtscToggle (31). flFun2 contains a bit mask similar to flFunl . 
The only difference is the functions that it registers. Each bit 
registers one or more of the following functions: VioModewait (0), 
VioModeundo (1), VioGetFont (2), VioGetconfig (3), Viosetcp (4), 
VioGetcp (5), ViosetFont (6), VioGetstate (7), Viosetstate (8), 
VioRegister (9), and VioDeRegister (10). You must always set bits 11 
through 31 to zero. usBeturn is reserved; always set it to zero. 
VioGlobalReg returns one of the following values: 


0 NO ERROR 


349 ERkoR VIO INVALID MASK 
403 ERROR-VIO-INVALID-ASCIIZ 
426 ERROR-VIO-REGISTE-R 
494 ERROR-VIO-EXTENDED SG 


When OS/2 routes control to the entry point of your DLL, it passes 
four additional values: index number (WORD), a near pointer 
(WORD), the caller's DS register (WORD), and the return address to 
the VIO router (DWORD). Each registered function has its own 
index number as shown here: 


0 VioGetphysBuf 4 VioGetcurType 
1 VioGetBuf 5 VioGetMode 
2 VioshowBuf 6 Viosetcurpos 
3 VioGetcurpos 7 ViosetcurType 


8 ViosetMode 
9 VioReadcharstr 
10 VioReadcellstr 
11 ViowrtNchar 


Function 


XWPM 
Ushort 
VioModeundo 
(usownerlnd, 
usKilllnd, 
usBeserved) 


XWPM 
Ushort VioModewait 
(usBeqType, 
pNotifyType, 
usBeserved) 


Description 


12 ViowrtNAttr 


13 ViowrtNcell 
14 Viowrtcharstr 
15 ViowrtcharstrAtt 
16 Viowrtcellstr 
17 Viowrfrm 


18 Vioscrollup 


19 VioscrollDn 


20 VioscrollLf 


21 VioscrollRt 


22 ViosetAnsi 


23 VioGetAnsi 
24 Vioprtsc 


25 VioscrLock 
26 Vioscrunlock 


27 ViosavRedrawwait 
28 ViosavRedrawundo 
29 Viopopup 


30 VioEndpopup 


31 VioprtscToggle 


32 VioModewait 


33 VioModeundo 


34 VioGetFont 


35 VioGetconfig 
36 Viosetcp 
37 VioGetcp 


38 ViosetFont 
39 VioGetstate 
40 Viosetstate 


41 VioRegister 


42 VioDeRegister 


The VioModeundo function allows a thread to cancel a VioModewait 
issued by another thread in the same process. usownerlnd tells 
OS/2 whether the thread wants to reserve ownership of 
VioModewait for its process. It can contain two values: reserve 
ownership (0) or give up ownership (1). usKilllnd tells OS/2 to return 
an error code or terminate the thread with the outstanding 
VioModewait. It can contain two values: return error code (0) or 
terminate thread (1). usBeserved is a reserved word; always set it to 
0. VioModeundo returns one of the following values: 


0 NO ERROR 


421 EREOR VIO INVALID PARMS 
422 ERROR-VIO-FUNCTION OWNED 
427 ERROR-VIO-NO MODE-THREAD 
430 ERROR-VIO-ILLEGAL D-URING POPUP 
465 ERROR-VIO-DETACHED 
486 ERROR-VIO-BAD RESERVE 
494 ERROR-VIO-EXTENDED SG 


The VioModewait function provides a graphics mode application 
with the means for automatically restoring its video mode, state, 
and modified display adapter registers. The application must 
perform this task each time this function returns. usBeqType 
determines the event that VioModewait monitors. The only 
acceptable value is 0, which notifies the application after a pop-up 
to restore its display. pNotifyType contains the address of the 
restoration routine. Restore mode (0) is the only type of notification 
returned. usBeserved is a reserved word; always set it to 0. 
VioModewait returns one of the following values: 


0 NO ERROR 


421 ERROR VIO INVALID PARMS 
422 ERROR-VIO-FUNCTION OWNED 
423 ERROR-VIO-RETURN 


Table 3 -2 Continued 


Command 


XPM 
Ushort Viopopup 
(pflags, hvio) 


XWPM 
Ushort Vioprtsc 
(hvio) 


XWPM 
Ushort 
VioprtscToggle 
(hvio) 


Description 


424 ERROR SCS INVALID FUNCTION 
428 ERROR-VIO-NO SAVE RESTORE THD 
430 ERROR-VIO-ILLEGAL -DURING P-OPUP 
465 ERROR-VIO-DETACHED 
494 ERROR-VIO-EXTENDED SG 
The Viopopup function provides a temporary screen that an 
application can use to display messages to the user. OS/2 allows 
only one pop-up at any time. You normally use a pop-up to inform 
the user of an error condition or other emergency information. The 
current foreground application cannot continue until the thread that 
issued the Viopopup issues a VioEndpopup. pflags contains the 
address of the flags used to set up the pop-up. Bit 0 returns a unique 
error code if a pop-up is not available when set to 0. It waits for a 
pop-up if one is not available when set to 1. Bit 1 selects 
nontransparent operation when set to 0 or transparent operation 
when set to 1. OS/2 automatically selects text mode (3, 3*, 3+, 7, 
or 7+) when you select nontransparent mode. It also clears the 
display and places the cursor in the upper-left corner. No mode 
changes occur if the display adapter already is in modes 2, 3, or 7 
when using transparent mode. OS/2 does not clear the display or 
change the cursor position. If the display is not in a text mode or the 
foreground process has a ViosavRedrawwait thread, then OS/2 
returns an error code. Bits 2 through 15 are reserved; always set 
them to 0. hvio contains a handle to the video buffer. Viopopup 
returns one of the following values: 


0 NO ERROR 


405 EREOR VIO NO POPUP 
406 ERROR-VIO-ExisTING POPUP 
483 ERROR-VIO-TRANSPA-RENT POPUP 
The Vioprtsc function sends the contents of the screen buffer to the 
printer. It supports text video modes 0 through 3 and 7. This is the 
call issued by the session manager when the user presses Prtsc. 
Application programs cannot issue this call. hvio contains a handle 
to the video buffer. Vioprtsc returns one of the following values: 


0 NO ERROR 


355 EREOR VIO MODE 
402 ERROR-VIO-SMG ONLY 
436 ERROR-VIO-INVALID HANDLE 
465 ERROR-VIO-DETACH-ED 
The VioprtscToggle function changes the Ctrl-Prtsc state of the 
foreground session. Setting this state on sends all output to the printer. 
This is the call issued by the session manager when the user presses 
Ctrl-Prtsc. Application programs cannot issue this call. hvio contains 
a handle to the video buffer. VioprtscToggle returns one of the 
following values : 


Function 


FAPI 
Ushort 
VioBeadcellstr 
(pchcellstr, pob, 
usBow, uscolumn, 
hvio) 


EAPI 
Ushort 
VioBeadcharstr 
(pchcellstr, pcb, 
usBow, uscolumn, 
hvio) 


XWPM 
Ushort VioBegister 
(pszModName, 
pszEntryName, 
flFunl , flFun2) 


Description 


0 NO ERROR 


355 EREOR VIO MODE 
402 ERROR-VIO-SMG ONLY 
430 ERROR-VIO-ILLEGAL DURING POPUP 
436 ERROR-VIO-INVALID -HANDLE- 
465 ERROR-VIO-DETACH-ED 


The VioReadcellstr function reads a string of character-attribute 
pairs from the screen starting at the specified location. pchcellstr 
contains the address of the buffer used to store the character- 
attribute pairs. pcb contains the address of the variable that stores 
the buffer length. Each character-attribute entry consumes two or 
four bytes (depending on mode). usBow contains the starting row to 
read (0 is at the top of the display). uscolumn contains the starting 
column to read (0 is at the left side of the display). hvio contains a 
handle to the video buffer. VioReadcellstr returns one of the 
following values: 


0 NO ERROR 


355 ERROR VIO MODE 
358 ERROR-VIO-ROW 
359 ERROR-VIO-COL 
436 ERROR-VIO-INVALID HANDLE 
465 ERROR-VIO-DETACH-ED 


The VioReadcharacterstr function reads a string of characters from 
the screen starting at the specified location. pchcellstr contains the 
address of the buffer used to store the characters. pob contains the 
address of the variable that stores the buffer length. usBow contains 
the starting row to read (0 is at the top of the display). uscolumn 
contains the starting column to read (0 is at the left side of the display). 
hvio contains a handle to the video buffer. VioReadcharacterstr 
returns one of the following values: 


0 NO ERROR 


355 EREOR VIO MODE 
358 ERROR-VIO-ROW 
359 ERROR-VIO-COL 
436 ERROR-VIO-INVALID HANDLE 
465 ERFIOR-VIO-DETACH-ED 


The VioRegister function registers an alternate video 
subsystem within the session. pszModName contains the address 
of a one to eight character ASCIIZ string that identifies the 
subsystem. You must use a DLL for the subsystem name. Do not 
include the DLL extension as part of the name. pszEntryName 
contains an address to a 1-to 32-character ASCIIZ string that 
identifies the entry point within the DLL. This is the routine that 
receives control when another thread executes a registered VIO 
function in a full screen session. flFunl contains a bit mask that 
identifies the video functions that you want registered. Push the 


Table 3-2 Continued 


Function 
Description 


high-order 16 bits onto the stack first, then the low-order 16 bits. 
Each bit registers one or more of the following functions: 
VioGetcurpos (0), VioGetcurType (1), VioGetMode (2), VioGetBuf 
(3), VioGetphysBuf (4), Viosetcurpos (5), ViosetcurType (6), 
ViosetMode (7), VioshowBuf (8), VioReaccharstr (9), 
VioReadcellstr (10), ViowrtNchar (11), ViowrtNAttr (12), 
ViowrtNcell (13), ViowrtlTY (14), Viowrtcharstr (15), 
ViowrtcharstrAtt (16), Viowrtcellstr (17), Vioscrollup (18), 
VioscrollDn (19), VioscrollLf (20), VioscrollRt (21), ViosetAnsi 
(22), VioGetAnsi (23), Vioprtsc (24), VioscrLock (25), 
Vioscrunlock (26) , ViosavRedrawwait (2 7) , ViosavRedrawundo 
(28), Viopopup (29), VioEndpopup (30), and VioprtscToggle (31). 
flFun2 contains a bit mask similar to flFun 1. The only difference is 
the functions that it registers. Each bit registers one or more of the 
following functions: VioModewait (0), VioModeundo (1), 
VioGetFont (2), VioGetconfig (3), Viosetcp (4), VioGetcp (5), 
ViosetFont (6), VioGetstate (7), Viosetstate (8), VioRegister (9), 
and VioDeRegister (10). You must always set bits 11 through 31 to 
zero. VioRegister returns one of the following values: 


0 NO ERROR 


349 EREOR VIO INVALID MASK 
403 ERROR-VIO-INVALID-ASCIIZ 
426 ERROR-VIO-REGISTE-R 
430 ERROR-VIO-ILLEGAL DURING POPUP 
465 ERROR-VIO-DETACHED 
494 ERROR-VIO-EXTENDED SG 


When OS/2 routes control to the entry point of your DLL, it passes 
four additional values: index number (WORD), a near pointer 
(WORD), the caller's DS register (WORD), and the return address to 
the VIO router (DWORD). Each registered function has its own 
index number as shown here: 


0 VioGetphysBuf 


1 VioGetBuf 


2 VioshowBuf 


3 VioGetcurpos 
4 VioGetcurType 


5 VioGetMode 
6 Viosetcurpos 
7 ViosetcurType 


8 ViosetMode 


9 VioReadcharstr 


10 VioReadcellstr 
11 ViowrtNchar 


12 Viowr[NAttr 


13 ViowrtNcell 
14 Viowrtcharstr 
15 ViowrtcharstrAtt 
16 Viowrtcellstr 
17 Viowrt" 


18 Vioscrollup 


19 VioscrollDn 


20 VioscrollLf 


21 VioscrollRt 


22 ViosetAnsi 


23 VioGetAnsi 
24 Vioprtsc 


25 VioscrLock 
26 Vioscrunlock 


Function 


XWPM 
Ushort 
ViosavBedraw- 
Undo 
(usownerlnd, 
usKilllnd 
uspeserved) 


XWPM 
Ushort 
ViosavBedrawwait 
(usBedrawlnd, 
pNotifyType, 
usBeserved) 


Description 


27 ViosavRedrawwait 33 VioModeundo 39 VioGetstate 


28 ViosavRedrawundo 34 VioGetFont 40 Viosetstate 


29 Viopopup 35 VioGetconfig 41 VioRegister 


30 VioEndpopup 36 Viosetcp 42 VioDeRegister 


31 VioprtscToggle 37 VioGetcp 


32 VioModewait 38 ViosetFont 


The router interprets the return code from a registered function as 
follows: 


0 = No Error. Do not invoke the corresponding Base Video 
Subsystem routine. Return to the caller with a return code of 0. 
-1 = No Error. Invoke the corresponding Base Video Subsystem 
routine. Return to the caller with a return value from the Base Video 
Subsystem. 


Other Number = Error. Do not invoke the corresponding Base 
Video Subsystem routine. Return the error number to the caller. 


The ViosavRedrawundo function allows a thread to cancel a 
ViosavRedrawwait issued by another thread in the same process. 
usownerlnd tells OS/2 whether the thread wants to reserve 
ownership of ViosavRedrawwait for its process. It can contain two 
values: reserve ownership (0) or give up ownership (1). usKillnd 
tells OS/2 to return an error code or terminate the thread with the 
outstanding ViosavRedrawwait. It can contain two values: return 
error code (0) or terminate thread (1). usBeserved is a reserved 
word; always set it to 0. ViosavRedrawundo returns one of the 
following values: 


0 NO ERROR 


421 EREOR VIO INVALID PARMS 
422 ERROR-VIO-FUNCTION OWNED 
428 ERROR-VIO-NO SAVE RESTORE THD 
430 ERROR-VIO-ILLEGAL -DURING Pbpup 
465 ERROR-VIO-DETACHED 
494 ERROR-VIO-EXTENDED SG 


The ViosavRedrawwait function notifies a graphics-mode 
application when it should save or redraw the screen. Only one 
process per session can issue this call. The application must 
perform this task each time this function returns. usBedrawlnd 
determines the event that ViosavRedrawwait monitors. There are 
two different values for the parameter. A value of 0 notifies the 
application of both save and redraw operations. A value of 1 notifies 
the application of redraw operations only. pNotifyType contains the 
address of the operation routine. A value of 0 saves the screen 
image. A value of 1 restores the screen image. usBeserved is a 


Table 3 -2 Continued 


Function 


FAPI XWPM 
Ushort VioscrLock 
(fwait, pfNot 
Locked, hvio) 


FAPI 
Ushort VioscrollDn 
(usTopRow, 
usBotBow, 
usLeftcol, 
usBightcol, 
hvio) pcell, hvio) 


Description 


reserved word; always set it to 0. ViosavRedrawwait returns one of 
the following values: 


0 NO ERROR 


421 EREOR VIO INVALID PARMS 
422 ERROR-VIO-FUNCTION OWNED 
423 ERROR-VIO-RETURN 
430 ERROR-VIO-ILLEGAL DURING POPUP 
436 ERROR-VIO-INVALID -HANDLE- 
465 ERROR-VIO-DETACH-ED 
494 ERROR-VIO-EXTENDED SG 


The VioscrLock function requests ownership of the physical display 
buffer. This locks out any other application that might want to use it. 
OS/2 disables screen switching while the lock is in place. Only one 
thread can own the screen locks. fwait contains a flag that tells 
OS/2 whether the process wants to wait until the screen I/0 can 
take place. A value of 0 returns immediately if the screen I/0 is not 
available. A value of 1 waits until the screen I/0 is available. 
pfNotLocked contains a pointer to a variable which contains a flag 
showing whether the lock is successful. On return from the call a 
value of 0 indicates success, while a value 1 indicates failure. hvio 
contains a handle to the video buffer (a reserved word of zeros in 
this case). VioscrLock returns one of the following values: 


0 NO ERROR 


366 ERROR VIO WAIT FLAG 
430 ERROR-VIO-ILLEG-AL DURING POPUP 
434 ERROR-VIO-LOCK 
436 ERROR-VIO-INVALID HANDLE 
465 ERROR-VIO-DETACH-ED 
494 ERROR-VIO-EXTENDED SG 


The VioscrollDn function scrolls the entire or defined area of the 
screen down. A value of 0 for both usTopRow and usLeftcol 
equates to the upper-left corner of the display. Using a value of 0 for 
usTopBow and usLeftcol, and a value of 65,535 (-1 for assembler) 
for usBotBow, usBightcol, and cbLines fills the entire area with the 
contents of pcell. usTopBow contains the top row to scroll. usLeftcol 
contains the leftmost column to scroll. usBotBow contains the bottom 
row to scroll. usBightcol contains the rightmost column to scroll. 
cbLines tells how many lines to scroll. pcell contains the address of a 
variable that contains a fill character to use for the scrolled lines. hvio 
contains a handle to the video buffer. VioscrollDn returns one of the 
following values : 


0 NO ERROR 


355 ERROR VIO MODE 
358 ERROR-VIO-ROW 


Function 


FAPI 
Ushort 
VioscrollLf 
(usTopF3ow, 
usLeftcol, 
usBotBow, 
usBightcol, cbcol, 
pcell, hvio) 


EAPI 
Ushort VioscrollBt 
(usTopF3ow, 
usLeftcol, 
usBotBow, 
usBightcol, 
cbcol,pcell, hvio) 


FAPI 
Ushort Vioscrollup 
(usTopRow, 
usLeftcol, 
usBotpow, 
usBightcol, 
cbLines,pcell, hvio) 


Description 


359 ERROR VIO COL 
436 ERROR-VIO-INVALID HANDLE 
465 ERROR-VIO-DETACH-ED 


The VioscrollLf function scrolls the entire or defined area of the 
screen to the left. A value of 0 for both usTopBow and usLeftcol 
equates to the upper|eft corner of the display. Using a value of 0 
for usTopBow and usLeftcol, and a value of 65,535 (-1 for 
assembler) for usBotBow, usBightcol, and cbcol fills the entire 
area with the contents of pcell. usTopBow contains the top row 
to scroll. usLeftcol contains the leftmost column to scroll. 
usBotBow contains the bottom row to scroll. usBightcol contains 
the rightmost column to scroll. cbcol tells how many columns to 
scroll. pcell contains the address of a variable that contains a fill 
character to use for the scrolled lines. hvio contains a handle to the 
video buffer. VioscrollLf returns one of the following values: 


0 NO ERROR 


355 ERROR VIO MODE 
358 ERROR-VIO-ROW 
359 ERROR-VIO-COL 
436 ERROR-VIO-INVALID HANDLE 
465 ERROR-VIO-DETACH-ED 


The VioscrollRt function scrolls the entire or defined area of the screen 
to the right. A value of 0 for both usTopBow and usLeftcol equates to 
the upper-left corner of the display. Using a value of 0 for usTopBow 
and usLeftcol, and a value of 65,535 (-1 for assembler) for 
usBightcol, and cbcol fills the entire area with the contents of pcell. 
usTopBow contains the top row to scroll. usLeftcol contains the 
leftmost column to scroll. usBotBow contains the bottom row to scroll. 
usBightcol contains the rightmost column to scroll. cbcol tells how 
many lines to scroll. pcell contains the address of a variable that 
contains a fill character to use for the scrolled lines. hvio contains a 
handle to the video buffer. VioscrollRt returns one of the following 
values: 


0 NO ERROR 


355 EREOR VIO MODE 
358 ERROR-VIO-ROW 
359 ERROR-VIO-COL 
436 ERROR-VIO-INVALID HANDLE 
465 ERROR-VIO-DETACH-ED 


The Vioscrollup function scrolls the entire or defined area of the 
screen up. A value of 0 for both usTopBow and usLeftcol equates 
to the upper-left corner of the display. Using a value of 0 for 
usTopF3ow and usLeftcol, and a value of 65,535 (-1 for assembler) 
for usBotBow, usBightcol, and cbLines fills the entire area with the 
contents of pcell. usTopBow contains the top row to scroll. 
usLeftcol contains the leftmost column to scroll. usBotBow contains 
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Command 


FAPI XWPM 
Ushort 
VioscrunLock (hvio) 


XPM 
Ushort ViosetAnsi 
(fAnsi, hvio) 


XPM 
Ushort Viosetcp 
(usBeserved, 
idcodepage, hvio) 


Description 


the bottom row to scroll. usBightcol contains the rightmost column 
to scroll. cbLines tells how many lines to scroll. pcell contains the 
address of a variable that contains a fill character to use for the scrolled 
lines. hvio contains a handle to the video buffer. Vioscrollup returns 
one of the following values: 


0 NO ERROR 


355 ERkoR VIO MODE 
358 ERROR-VIO-ROW 
359 ERROR-VIO-COL 
436 ERROR-VIO-INVALID HANDLE 
465 ERROR-VIO-DETACH-ED 


The VioscrunLock function releases ownership of the physical 
display buffer. This unlocks the physical display buffer so that all 
applications can use it. Only the thread that issued the VioscrLock 
call can call this function. hvio contains a handle to the video buffer 
(a reserved word of zeros in this case). VioscrunLock returns one of 
the following values: 


0 NO ERROR 


367 ERROR VIO UNLOCK 
430 ERROR-VIO-ILLEGAL DURING POPUP 
436 ERROR-VIO-INVALID -HANDLE- 
465 ERROR-VIO-DETACH-ED 
494 ERROR-VIO-EXTENDED SG 


The ViosetAnsi function sets the state of the ANSI flag. This 
determines whether OS/2 can process ANSI escape sequences. 
fAnsi is a pointer to a variable that contains the ANSI flag. Setting 
this flag to 1 activates ANSI support. hvio contains a handle to the 
video buffer. ViosetAnsi returns one of the following values: 


0 NO ERROR 


355 EREOR VIO MODE 
421 ERROR-VIO-ILLEGAL PARMS 
430 ERROR-VIO-ILLEGAL-DURING POPUP 
436 ERROR-VIO-INVALID -HANDLE- 
465 ERROR-VIO-DETACH-ED 


The Viosetcp function sets the current code page used to display 
text data. usBeserved contains a value of zero. idcodepage 
contains a word used to store the code page number. There are four 
code page values that you can use: 0 (default ROM), -1 (user front 
code page), -2 (disables user font code page and returns system to 
either a prepared or ROM code page), or a value specified with the 
CODEPAGE= statement in CONFIG.SYS. You cannot use values of 
-1 or -2 for Presentation Manager sessions. hvio contains a handle to 
the video buffer. Viosetcp returns one of the following values: 


Function 


FAPI 
Ushort 
Viosetcurpos 
(usF3ow, uscolumn, 
hvio) 


EAPI 
Ushort 
ViosetcurType 
(pviocursorlnfo 
hvio) 


Description 


0 NO ERROR 
355 EREOR VIO MODE 
436 ERROR-VIO-INVALID HANDLE 
465 ERROR-VIO-DETACH-ED 
469 ERROR-VIO-BAD CP 
470 ERROR-VIO-NO €P 
471 ERROR-VIO-NA-CP 


The Viosetcurpos function returns the current row and column 
coordinates of the cursor. usBow contains the row setting. 
puscolumn contains the column setting. A value of 0 in both 
variables indicates the cursor is in the upper left corner of the 
display. hvio contains a handle to the video buffer. Viosetcurpos 
returns one of the following values: 


0 NO ERROR 


355 EREOR VIO MODE 
358 ERROR-VIO-ROW 
359 ERROR-VIO-COL 
436 ERROR-VIO-INVALID HANDLE 
465 ERROR-VIO-DETACH-ED 
The ViosetcurType function changes the cursor type. pviocursorl nfo 
contains a pointer to a structure containing the cursor information. 
hvio contains a handle to the video buffer. The pviocursorlnfo data 
structure consists of the following elements: 


Offset Length Description 


Ooh 2 The top horizontal scan line of the cursor within a 


character cell. You also can specify this number as 
a percentage of the total scan lines by supplying 
a negative number in the range 0 to -100. 


02h2 


04h2 


06h2 


The bottom horizontal scan line of the cursor 
within a character cell. You also can specify this 
number as a percentage of the total scan lines 
by supplying a negative number in the range 
0 to -100. 
Cursor Width. In character mode, the cursor 
width equals the number of character columns 
on the display. In graphics mode, the cursor 
width is measured in pels. 
Cursor Attribute. A value of -1 indicates a 
hidden cursor. Any other value in text mode 
indicates that the user can see the cursor. In 
graphics mode, any other number indicates the 
color of the cursor. 


ViosetcurType returns one of the following values: 
0 NO ERROR 


Table 3 -2 Continued 


Function 


FAPI XWPM 
Ushort ViosetFont 
(pviofi, hvio) 


FAPI XPM 
Ushort ViosetMode 
(pvioModelnfo, 
hvio) 


Description 


355 ERROR VIO MODE 
356 ERROR-VIO-WIDTH 
421 ERROR-VIO-INVALID PARMS 
436 ERROR-VIO-INVALID-HANDLE 
465 ERROR-VIO-DETACH-ED 
The ViosetFont function changes the display font to a font that is 
specified. You must use a font that is compatible with the current 
video mode. pviofi contains a pointer to a table used to store the 
font data. hvio contains a handle to the video buffer. The pviofi data 
structure consists of the following elements: 
Offset Length Description 
Ooh 2 Length of structure.14 is the only correct value. 
02h 2 Request Type. A value of o uses the current 


RAM font for EGA, VGA, or SVGA display 
adapters. 


04h 2 Pel columns in character cell. 


06h 2 Pel rows in character cell. 
08h 4 Pointer to a block of storage space in the 


application data area that contains the font 
table. 


Och 2 Length of the caller-supplied font table storage 


area in bytes. 


ViosetFont returns one of the following values: 


0 NO ERROR 


355 EREOR VIO MODE 
421 ERROR-VIO-INVALID PARMS 
436 ERROR-VIO-INVALID-HANDLE 
438 ERROR-VIO-INVALID-LENGTH 
465 ERROR-VIO-DETACH-ED 
467 ERROR-VIO-FONT 
468 ERROR-VIO-USER FONT 
494 ERROR-VIO-EXTEivDED SG 


The ViosetMode function changes the current display mode 
information. It also initializes the cursor position and type. It does 
not clear the screen. pvioModelnfo contains a pointer to a table 
used to store the mode data. hvio contains a handle to the video 
buffer. The pvioModel nfo data structure consists of the following 
elements: 
Offset I.ength Description 


Ooh 2 Length of structure. The value that you supply 


controls the amount of display mode data 


Description 
Offset Length 


02h1 


Description 


changed. The minimum value is 3 and the 
maximum is 34. 


Mode characteristics bit mask. The disable color 
burst setting works only with CGA and VGA 
displays. 
0 0 = Monochrome compatible mode 


1 - Other 


1 0 = Text mode 


1 = Graphics mode 


2 0 = Enable color burst 


1 = Disable color burst 


3 0 = VGA compatible modes o-13h 


1 = Native mode 


4-7 Reserved 
Number of colors defined as a power of two: 
0 = monochrome 
1 = 2 colors 
2 = 4 colors 
4 = 16 colors 
8 = 256 colors 


2 Number of text columns 
2 Number of text rows 
2 Horizontal resolution in pels 


2 Vertical resolution in pels 
1 Format of the attributes 
1 Number of attributes in a character cell. 
4 32-bit address of the physical display buffer for 


this mode. 


4 Length of the physical display buffer for this mode. 
4 Size of the buffer required for a full save of the 


physical display buffer for this mode. 
1AI4 


1Dh4 


Size of the buffer required for a partial (pop-up) 
save of the physical display buffer for this mode. 
Far address to the extended mode data structure. 
The format of this structure varies by display 
adapter and is unknown to OS/2. Set this value 
to 0 if there is no extended mode data. 


ViosetMode returns one of the following values: 


0 NO ERROR 


355 ERROR VIO MODE 
430 ERROR-VIO-ILLEGAL DURING POPUP 


Table 3 -2 Continued 


Function 


FAPI XWPM 
Ushort 
Viosetstate 
(pstate, hvio) 


Description 


436 ERROR VIO INVALID HANDLE 
438 ERROR-VIO-INVALID-LENGTH 
465 ERROR-VIO-DETACH-ED 
467 ERROR-VIO-FONT 
468 ERROR-VIO-USER FONT 
494 ERROR-VIO-EXTEivDED SG 


The Viosetstate function changes one of several types of 
information about the video adapter. This includes the various types 
of register information. pstate contains a pointer to a structure. 
There are six different structures; each one corresponds to a 
particular structure. The structure types include: set palette registers 
(0), set overscan color (1), set blink/background intensity switch (2), 
set color registers (3), set the scan line for underlining (5), and set 
target display configuration (6). Types 4 and 7 currently are 
reserved. hvio contains a handle to the video buffer. The pstate 
data structure consists of the following elements (depending on the 
type of request you make): 
Offset I+ength Description 


Set palette registers (Viopalstate) 


2 Length of structure. (Maximum length of 38 


allowed.) 


2 Set to o for palette registers. 


2 First palette register in the register sequence. 


You must supply a value between 0 and 15. 


06h-XX 2 per One entry for each palette registerthat 


entry you want to set. You can specify a maximum 


of 16 register entries. 


Set ouerscan color (Vioouerscan) 


00h 2 Length of structure. The only valid value is 6. 


02h 2 Set to 1 for overscan (border) color. 


04h 2 Color value 


Set blink/background intensity su)itch (Violntensity) 


2 Length of structure. The only valid value is 6. 


2 Set to 2 for blink/background intensity switch. 


2 Use the following values to set the switch: 


0 = Blinking colors enabled 
1 = High-intensity colors enabled 


Function 
Description 
Offset Length Description 


Set color registers (ViocolorReg) 
00h2 
02h2 
04h2 


06h2 


08h4 


Length of structure. The only valid value is 12. 


Set to 3 for color registers. 


Value of the first color register value to set 
(0-255). The color registers are changed in 
sequential order. 


Number of color registers that you want to set 
(1-256). 
Pointer to a data area to use to store the 
register values. Multiply the number of registers 
that you want to retrieve by 3 bytes to 
determine the size of the data area that is 
needed. Each register entry contains one byte 
of color information in the following order: 
red, green, and blue. 


Set the scan line for underlining (ViosetulineLoc) 
00h2 
02h2 


04h2 


Length of structure. The only valid value is 6. 


Set to 5 to set the scan line for underlining. 
You can use this feature only if the foreground 
color is 1 or 9. You cannot use this value in a 
family API application. 


Value of the scan line in the range 0 to 31. 
Setting this entry to 32 disables underlining. 


Set target display configuration (ViosetTarget) 


00h 2 Length of structure. The only valid value is 6. 


02h 2 Set to 6 to set the display configuration that 


you want to select as the target for the next 
ViosetMode function call. You cannot use this 
value in a family API application. 


04h2 
Configuration value: 0 for default selection, 1 
for primary, or 2 for secondary. 


Viosetstate returns one of the following values: 


0 NO ERROR 


355 EREOR VIO MODE 
421 ERROR-VIO-INVALID PARMS 
436 ERROR-VIO-INVALID-HANDLE 
438 ERROR-VIO-INVALID-LENGTH 
465 ERROR-VIO-DETACH-ED 
494 ERROR-VIO-EXTENDED SG 


Table 3-2 
Continued 


Function 


XPM 
Ushort 
VioshowBuf (offLVB, 
cb, hvio) 


FAPI 
Ushort Viowrtcellstr 
(pchcellstr, cb, 
usBow, uscolumn, 
hvio) 


FAPI 
Ushort 
Viowrtcharstr (pch, 
cb, usBow, 
uscolumn, hvio) 


FAPI 
Ushort 
ViowrtcharstrAtt 
(pch, cb, usBow, 


Description 


The VioshowBuf function updates the physical display buffer (PDB) 
with the contents of the logical video buffer (IJVB). offLVB contains 
the starting position within the IJVB to use to update the PDB. Cb 
contains the length of the update. hvio contains a handle to the 
video buffer. VioshowBuf returns one of the following values: 


0 NO ERROR 


355 EREOR VIO MODE 
430 ERROR-VIO-ILLEGAL DURING POPUP 
436 ERROR-VIO-INVALID -HANDLE- 
465 ERROR-VIO-DETACH-ED 
The Viowrtcellstr function writes a string of character-attribute pairs 
to the screen starting at the specified location. The write always 
terminates at the end of the physical display even if the buffer is not 
exhausted. pchcellstr contains the address of the buffer used to 
store the character-attribute pairs. cb contains the length of the string. 
Each character-attribute entry consumes two or four bytes (depending 
on the mode). usBow contains the starting row to write (0 is at the 
top of the display). uscolumn contains the starting column to write 
(0 is at the left side of the display). hvio contains a handle to the 
video buffer. Viowrtcellstr returns one of the following values: 


0 NO ERROR 


355 EREOR VIO MODE 
358 ERROR-VIO-ROW 
359 ERROR-VIO-COL 
436 ERROR-VIO-INVALID HANDLE 
465 ERROR-VIO-DETACH-ED 
The Viowrtcharstr function writes a string of characters to the 
screen starting at the specified location. The write always terminates 
at the end of the physical display even if the buffer is not exhausted. 
pch contains the address of the buffer used to store the string. cb 
contains length of the string. usBow contains the starting row to 
write (0 is at the top of the display). uscolumn contains the starting 
column to write (0 is at the left side of the display). hvio contains a 
handle to the video buffer. Viowrtcharstr returns one of the 
following values: 


0 NO ERROR 


355 EREOR VIO MODE 
358 ERROR-VIO-ROW 
359 ERROR-VIO-COL 
436 ERROR-VIO-INVALID HANDLE 
465 ERROR-VIO-DETACH-ED 


The ViowrtcharstrAtt function writes a string of character string 
with a repeated attribute to the screen starting at the specified 
location. The write always terminates at the end of the physical cb, 
display even if the buffer is not exhausted. pch contains the address 


Function 
uscolumn, pAttr, 
hvio) 


FAPI 
Ushort ViowrtNAttr 
(pAttr, cb, usBow, 
uscolumn, hvio) 


EAPI 
Ushort ViowrtNcell 
(pcell, cb, usBow, 
uscolumn, hvio) 


FAPI 
Ushort ViowrtNchar 


Description 
of the buffer used to store the string. cb contains the length of the 
string. usBow contains the starting row to write (0 is at the top of 
the display). uscolumn contains the starting column to write (0 is at 
the left side of the display). pAttr contains the address of the buffer 
used to store the attribute for the string (either one or three bytes). 
hvio contains a handle to the video buffer. ViowrtcharstrAtt returns 
one of the following values: 


0 NO ERROR 


355 EREOR VIO MODE 
3 5 8 ERROR-VIO-ROW 
35 9 ERROR-VIO-COL 
436 ERROR-VIO-INVALID HANDLE 
4 6 5 ERRO R-VIO-DETACH-ED 
The ViowrtNAttr function writes an attribute to the screen a 
specified number of times. The write always terminates at the end of 
the physical display even if the attribute does not appear the 
requested number of times. pAttr contains the address of the buffer 
used to store the attribute (either one or three bytes). cb contains 
the number of times to write the attribute. usBow contains the 
starting row to write (0 is at the top of the display). uscolumn 
contains the starting column to write (0 is at the left side of the 
display). hvio contains a handle to the video buffer. ViowrtNAttr 
returns one of the following values: 


0 NO ERROR 


355 ERROR VIO MODE 
358 ERROR-VIO-ROW 
359 ERROR-VIO-COL 
436 ERROR-VIO-INVALID HANDLE 
465 ERROR-VIO-DETACH-ED 
The ViowrtNcell function writes a character-attribute pair to the 
screen a specified number of times. The write always terminates 
at the end of the physical display even if the character-attribute pair 
does not appear the requested number of times. pcell contains the 
address of the buffer used to store the character-attribute pair (either 
two or four bytes). cb contains the number of times to write the 
character-attribute pair. usBow contains the starting row to write (0 
is at the top of the display). uscolumn contains the starting column 
to write (0 is at the left side of the display). hvio contains a handle to 
the video buffer. ViowrtNcell returns one of the following values: 


0 NO ERROR 


355 EREOR VIO MODE 
358 ERROR-VIO-ROW 
359 ERROR-VIO-COL 
436 ERROR-VIO-INVALID HANDLE 
465 ERROR-VIO-DETACH-ED 


The ViowrtNchar function writes a character to the screen a 
specified number of times. The write always terminates at the end of 


Table 3 -2 Continued 


Function 
(pchchar, cb, 
usRow, uscolumn, 
hvio) 


FAPI 
Ushort ViowrtTTY 
(pch, cb, hvio) 


Description 
the physical display even if the character does not appear the 
requested number of times. pchchar contains the address of the 
buffer used to store the character (either one or three bytes). cb 
contains the number of times to write the character. usBow contains 
the starting row to write (0 is at the top of the display). uscolumn 
contains the starting column to write (0 is at the left side of the 
display). hvio contains a handle to the video buffer. ViowrtNchar 
returns one of the following values: 


0 NO ERROR 


355 ERROR VIO MODE 
358 ERROR-VIO-ROW 
359 ERROR-VIO-COL 
436 ERROR-VIO-INVALID HANDLE 
465 ERROR-VIO-DETACH-ED 


The ViowrtlTY function writes a string of characters to the screen 
starting at the current location. The write always continues, even if it 
is at the end of the physical display. OS/2 simply scrolls the display 
to accommodate the extra text. pch contains the address of the 
buffer used to store the string. cb contains length of the string. hvio 
contains a handle to the video buffer. Viowrtcharstr returns one of 
the following values: 


0 NO ERROR 


355 ERffoR VIO MODE 
436 ERROR-VIO-INVALID HANDLE 
465 ERROR-VIO-DETACH-ED 


IBM did not choose to document these functions after version 1.3 of 
OS/2 because they are machine specific and IBM plans to port OS/2 
to other platforms. The current OS/2 implementation encourages 
the developer to write to the less machine-specific 


You still can use all these functions within your current applications, 
but there is no guaran-tee that IBM will support them in future 
versions of OS/2. Use Presentation Manager specific functions 
whenever possible in your applications. 


Some functions, like ViosetMode, require a mode number to work. 
The mode numbers for MDA, Hercules, CGA, and EGA adapters are 
standardized. VGA and SVGA adapters present a little more of a 
problem. Early VGA vendors had no standard to follow when they 
designed extensions to their display adapters. (IBM, the leader at the 
time, chose to make the 8514/A display its upgrade to the VGA.) 


SVGA vendors faced the same problem. As a result, every display 
adapter used its own set of codes for extended modes and every 
programmer had to take these modes into account. The Video 
Electronics Standards Association (VESA) worked with vendors to 
correct this situation. While every display adapter still uses its own set 
of modes, some display adapters also come with support for the 
VESA supported modes. You usually need to load this support 
through one of the display drivers. 


Table 3-3 provides a list of the modes commonly used with 
everything from CGA to SVGA displays. Notice that the table shows 
you the VESA specific display modes for the VGA and SVGA adapter 
types. Some vendors implement these same modes as 7-bit mode 
numbers accessed through standard BIOS calls. 


Standard display adapter display modes 
Table 3-3 


Mode Type Colors Resolution Glyph cell*** 


Oh Text 16 


1h Text 16 


Text 


Text 


Graphics 


Graphics 


Graphics 2 


Text Mono 


Graphics 16 


Eh Graphics 16 


Fh Graphics Mono 


10h Graphics 16 


llh Graphics 2 


12h Graphics 16 


13h Graphics 256 


400 by 360 
(25 by 40 characters) 
400 by 360 
(25 by 40 characters) 
400 by 720 


400 by 720 


200 by 320 
(25 by 40 characters) 
200 by 320 
(25 by 40 characters) 
200 t)y 640 


400 by 720 


200 by 320 
(25 by 40 characters) 
200 by 640 


350 by 640 


350 by 640 


480 by 640 


480 by 640 


200 by 320 


9 by 16 


9 by 16 


9 by 16 


9 by 16 
8by8 


8by8 


8by8 


9 by 16 
8by8 


8by8 


8 by 14 


8 by 14 


8 by 16 


8 by 16 
8by8 


Table 3-3 
Continued 


Mode Type Colors Resolution Glyph cell*** 


6AH* Graphics 16 


(100h* Graphics 256 
101h* Graphics 256 


102h* Graphics 16 


103h* Graphics 256 


104h* Graphics 16 


105h* Graphics 256 


106h* Graphics 16 


107h* Graphics 256 


108h** Text 16 


109h** Text 16 


10Ah** Text 16 


10Bh** Text 16 


10Ch** Text 16 


10Dh** Graphics 32K 


10Eh** Graphics 64K 


10Fh** Graphics 16.8M 


110h** Graphics 32K 


111h Graphics 64K 


112h Graphics 16.8M 


113h Graphics 32K 


114h Graphics 64K 


115h Graphics 16.8M 


116h Graphics 32K 


117h Graphics 64K 


600 by 600 
400 by 640 
480 by 640 


600 by 800 


600 by 800 


768 by 1024 


768 by 1024 


1024 by 1280 


1024 by 1280 


600 by 800 
(80 by 60 characters) 
600 by 800 
(132 by 25 characters) 
600 by 800 
(132 by 43 characters) 


600 t)y 800 
(132 by 50 characters) 
600 by 800 
(132 by 60 characters) 
200 by 320 
(25 by 40 characters) 
200 by 320 
(25 by 40 characters) 
200 by 320 
(25 by 40 characters) 
480 by 640 
480 by 640 
480 by 640 


600 by 800 
600 by 800 
600 by 800 


768 by 1024 


768 by 1024 


10 by 24 


8 by 16 


8 by 16 


10 by 24 


10 by 24 


12 by 30 


12 by 30 


16 by 40 


16 by 40 


10 by 10 


6 by 24 


6 by 14 


6 by 12 


6 by 10 


8by8 


8dy8 


8by8 


8 by 16 


8 by 16 


8 by 16 


10 by 24 


10 by 24 


10 by 24 


12 by 30 


12 by 30 


Mode Type Colors Resolution Glyphcell*** 


118h Graphics 16.8M 768byl024 12by30 


119h Graphics 32K 1024byl280 16by40 


llAh Graphics 64K 1024by 1280 16by40 


llBh Graphics 16.8M 1024byl280 16by40 


* 15-bit mode numbers are based on VESA Ivideo Electronics Standards Association) 


standard VS891001 for Super VGA resolution. Not all manufacturers use the 15-bit 
sequence. Some Super VGA display adapters use a 7-bit mode from 14h-7Fh. Mode 
6Ah is the only 7-bit Super VGA mode currently supported by the VESA standard. 
(See standard 800401 for more information on using the mode 6Ah extension.) 


** 15-bit mode numbers are based on VESA ovideo Electronics Standards Association) 


standard VS911022 for Super VGA resolution. There are no 7-bit extensions for the 
modes added by this standard. All extensions are 15-bit numbers. This standard does 
recognize the mode 6Ah extension of previous standards. 


*** Glyph cell size is determined by an 80x25 character display unless otherwise stated. 


The resolution is always stated. 


Some of the VIO functions will not work with advanced display 
adapters at all. The reason is simple, these adapters provide a host 
interface that makes their registers inaccessible to the standard OS/2 
routines. For example, the standard OS/2 routines will not support 
mode changes (ViosetMode) with advanced adapters like the 8514/A 
and XGA. Nor can you use VioGetMode to determine the current 
adapter mode. Notice that, even though VioGetconfig does provide 
limited support for advanced display adapters, it does not provide 
everything you need. As a result, you must program and read the 
registers of these adapters directly. 


Compare the VGA block diagram in Fig. 3-1 to those found in the 
TIGA, and XGA sections. A quick check makes it apparent that OS/2 
cannot access these adapters without a lot more information that a 
device driver could provide. The VGA allows full access to the CRTC, 
the registers, and all BIOS extensions; the advanced adapters usually 
accomplish their tasks through a processor or coprocessor. This is the 
reason that you must access these adapters directly to obtain the full 
range of flexibility and programming options they provide. The 
following paragraphs provide everything you need to perform this task. 


-*-8514/A display adapter The 8415/A display adapter 


provides a host interface that you use to access the registers. This 
display adapter does not usually operate by itself . It requires the 
addition of a VGA to access lower-resolution compatibility modes. 


Figure 3-1 


VGA block diagram. 


Table 3-4 shows the display modes accessible with a system equipped 
with an 8514/A display adapter. You can use these modes in addition 
to the ones shown in Table 3-3. 


8514/A display modes 


Model Type Colors Resolution Glyph cell 


Graphics 16/2561 480by640 8byl6 


Graphics 16/2561 768byl024 12by20 


Graphics 16/2561 768byl024 8byl4 


Graphics 16/2561 768byl024 7byl5 


1 Application Interface (AI) specific modes. Some 8514/A adapters support 


additional modes through the use of direct register programming. 


As stated previously, the standard 8514/A AI consists of an OS/2 
device driver. To access this program, use interrupt 7Fh after loading 
AX with the value 0105h. If successful, the CX:DX pair returns a 
segment and offset to the program entry table and the carry flag 


equals 0. The table contains 59 segment offset pairs for the calls 
listed in Table 3-5 in the order listed. 


8514/A Application Interface (AI) commands 
Table 3-5 


Command Number Function 


ABLOCKCGA 53 Writes a CGA-formatted alphanumeric character block. 


ABLOCKMF1 52 Writes an alphanumeric character block. 


ACURSOR 


AERASE 


ASCROLL 


ASCUR 


ASFONT 


AXLATE 


HEAR 


HBBC 


HBBCHN 


HBBR 


HBBW 


HCBBW 


HCCHST 
HCHST 


HCLINE 


HMRK 


56 Sets the alphanumeric cursor position. 


54 Erases a character cell rectangle. 


55 Scrolls the character cell rectangle. 


57 Sets the alphanumeric cursor shape. 


58 Selects the alphanumeric character font. 


59 Selects the alphanumeric attribute color index table. 


5 Begins a filled area. 


14 Performs Bit-BLT exclusively in display memory. 


13 Performs Bit-BLT to or from system memory. 


12 Defines the Bit-BLT source at an absolute address. 


10 Defines the Bit-BLT destination at an absolute address. 


11 Defines the Bit-BLT destination at the current cursor position. 


50 Places a text string at the current cursor position. 


49 Places a text string at an absolute position. 


Draws an absolute polyline starting at the current cursor 
position. 
Closes the display adapter interface. 


Draws a marker symbol at the current cursor position. 


Ends a filled area. 


Clears the screen. 


Terminate adapter processing. 


Initializes the task-dependent state buffer. 


Waits for the vertical retrace signal. 


Load a palette. 


Draws an absolute polyline starting at an absolute cursor 
position. 
Draws a marker symbol at an absolute position. 


Table 3 -5 Continued 


Command Number Function 


HOPEN 15 
HQCOORD 35 
HQCP 18 


HQDFPAL 19 
HQDPS 38 
HQMODE 24 


HQMODES 25 


HRCLINE 4 


HRECT 


HRLINE 
HRLPC 
HRPAL 
HSBCOL 
HSBP 
HSCMP 
HSCOL 


HSCOOFID 
HSCP 
HSCS 
HSGQ 
HSHS 
HSLPC 
HSLT 
HSLW 


HSMARK 
HSMODE 
HSMX 
HSPAL 
HSPATT 
HSPAITO 
HSYNC 
HXIAIE 


Opens the display adapter interface. 
Gets the coordinate types. 
Gets the current cursor position. 
Get default palette information. 
Gets drawing process buffer size. 
Gets the display adapter mode. 
Sees if a display adapter mode is available. 
Draws a relative polyline starting at the current cursor 
position. 
Draws a filled rectangle. 
Draws a relative polyline starting at an absolute position. 
Restores a saved line pattern position. 
Restores a saved palette. 
Sets the background color. 
Sets the display and masking bitplane controls. 
Sets the color comparison register. 
Sets the foreground color. 
Sets the coordinate types. 
Moves the cursor to an absolute position. 
Selects a character set. 
Sets the graphics quality/drawing styles. 


Clips a rectangle (scissors). 
Saves the current line pattern position. 
Sets the current line type. 
Sets the current line width. 
Sets the current marker shape. 
Sets the display adapter mode. 
Sets the drawing raster operation (mix). 
Save the current palette. 
Sets the current pattern shape. 
Sets the current pattern origin. 
Sets the adapter to a task-dependent state. 
Assigns a color index table for text. 


However, you can directly access the ports on an 8514/A adapter. 
VESA has adopted a standard set of register names, mnemonics, 
and addresses (standards VS890804 and VS900601) as listed in 
Table 3-6. (Note: The VS900601 standard also includes C header 
and assembler files that you can use while programming the 
8514/A adapter.) As indicated in the table, some registers use the 
read-only attribute, while others use the read-write attribute. 
Because each vendor could provide different functionality f or each 
register, you should refer to the vendor manual for a detailed 
description of the register functions. A generalized listing of 
register functions as listed in Chips and Technologies 82C480 
Programmer's Spec (Rev 2.1) follows. 


Standard 8514/A registers 


Port 


0100* 


0101* 


0102* 


02E8 


02E8 


02EA 


02EB 


02EC 


02ED 


06E8 


0AE8 


0EE8 


12E8 


16E8 


1AE8 


1EE8 


22E8 


42E8 


42E8 


Register name 


Setup Mode Identification 


Setup Mode Identification 


Setup Mode Option 


Display Status 


Horizontal Total 


DAC Mask 


DAC Read Index 


DAC Write Index 


DAC Data 


Horizontal Displayed 


Horizontal Sync Start 


Horizontal Sync Width 


Vertical Total 


Vertical Displayed 


Vertical Sync Start 


Vertical Sync Width 


Display Control 


Subsystem Status 


Subsystem Control 


Mnemonic 


SETUP IDI 


SETUP ID2 


SETUP OPT 


DISP STAT 


H TOTAL 


DAC MASK 


DAC R INDEX 


DAC W INDEX 


DAC DATA 


H DISP 


H SYNC STRT 


H SYNC WID 


V TOTAL 


V DISP 


V SYNC STRT 


V SYNC WID 


DISP CNTL 


SUBSYS STAT 


SUBSYS CNTL 


Type 


Read-Only 


Read-Only 


Read-Write 


Read-Only 


Write-Only 


Read-Write 


Read-Write 


Read-Write 


Read-Write 


Read-Write 


Read-Write 


Read-Write 


Read-Write 


Read-Write 


Read-Write 


Read-Write 


Read-Write 


Read-Only 


Write-Only 


Table 3 -6 Continued 


8EE8 


92E8 


96E8 


9AE8 


9AE8 


9EE8 


A2E8 


A6E8 


AAE8 


AEE8 


82E8 


86E8 


BAE8 


BEE8 


BEE8 Index 0 


BEE8 Index 1 


BEE8 Index 2 


BEE8 Index 3 


BEE8 Index 4 


BEE8 Index 5 


Register name 


ROM Page Select 


Advanced Function Control 


Current Y Position 


Current X Position 


Destination Y Position/ 
Axial Step Constant 


Destination X Position/ 
Axial Step Constant 


Error Term 


Major Axis Pixel Count 


Graphics Processor Status 


Command 


Short Stroke Vector Transfer 


Background Color 


Foreground Color 


Write Mask 


Read Mask 


Color Compare 


Background Mix 


Foreground Mix 


Multi-Function Control 


Minor Axis Pixel Count 


Top Scissors 


Left Scissors 


Bottom Scissors 


Right Scissors 


Memory Control 


Mnemonic 


ROM PAGE SEL 


ADVFUNC CNTL 


CURY 


CURX 


DESTY AXSTP 


DESTX AXSTP 


EFIR TERM 


MAJ AXIS PCNT 


GP STAT 


CMD 


SHORT STROKE 


BKGD COLOR 


FRGD COLOR 


WRT MASK 


RD MASK 


COLOR CMP 


BKGD MIX 


FRGD MIX 


MULTIFUNC CNTL 


MIN AXIS PCNT 


SCISSORS T 


SCISSORS L 


SCISSORS 8 


SCISSORS R 


MEM CNTL 


Type 


Read-Write 


Read-Write 


Read-Write 


Read-Write 


Read-Write 


Read-Write 


Read-Write 


Read-Write 


Read-Only 


Write-Only 


Read-Write 


Read-Write 


Read-Write 


Read-Write 


Read-Write 


Read-Write 


Read-Write 


Read-Write 


N/A 


Read-Write 


Read-Write 


Read-Write 


Read-Write 


Read-Write 


Read-Write 


Port Register name Mnemonic Type 


BEE8 Index 8 Fixed pattern Low PATTERN L Read-Write 


BEE8 Index 9 Fixed pattern High PATTERN H Read-Write 


BEE8 Index A Pixel control PIX CNTL Read-Write 


E2E8 Pixel Data Transfer PIX TRANS Read-Write 


* These register addresses do not appear in the VS900601 standard. They do appear in the 


VS890804 standard. 


Ports 100h, 101h, and 102h are Micro Channel Architecture (MCA) 
specific. You can read, but not write, to ports 100h and 101h. They 
provide the POS ID for the installed card. The IBM 8514/A adapter 
returns a value of EF7Fh. Use this port to determine if the machine 
contains an 8514/A adapter. Port 102h enables or disables the 
8514/A adapter. Placing a 1 in bit zero enables the card. You must 
set all other bits to zero. 


Ports 2E8h, 6E8h, AE8h, EE8h, 12E8h, 16E8h, 1AE8h, and lEE8h 
provide information about the vertical and horizontal sync 
parameters. Port 2E8h provides sync status when read. It sets the 
horizontal total register when written. The horizontal total equals the 
total length of the scan line including blanking. Horizontal total 
always begins with the first pixel of the scan line. Table 3-7 contains 
a complete bit listing for port 2E8h. Ports 6E8h, AE8h, and EE8h 
provide the means to read and write the remaining horizontal 
registers. These parameters include horizontal blank, horizontal sync, 
and horizontal sync pulse. Tables 3-8 through 3-10 provide bit 
information about these ports. Ports 12E8h, 16E8h, 1AE8h, and 
lEE8h provide read and write capability for all vertical registers. 
These registers include vertical total, vertical displayed, vertical sync 
start, and vertical sync width. Tables 3-11 through 3-14 provide bit 
information about these ports. 


Sync status and horizontal total (Port 02E8h) 


Bit Function 


Read - Sync Status 


0 Video sense 


0 - No Monitor Attached 


Table 3 -7 Continued 


Bit Function 


1 Monitor Attached 


1 Horizontal sync -End of scan Line 


2 Vertical sync -Start of vertical Retrace 


3-15 Notused 


Write - Horizontal Total 


0-7 Horizontal Total -Total scan Line width 


8-15 Notused 


Horizontal displayed (Port 6E+8h) 


Bit Function 


0-7 Horizontal Blank -Start of Blank pulse 


8-15 Notused 


Table 3-9 
Horizontal sync start (Port AE8h) 


Bit Function 


0-7 Horizontal sync start 


8-15 Notused 


Table 3-10 
Horizontal sync width (Port EE8h) 


Bit Function 


0-4 Horizontal sync width 


5 Horizontal sync polarity 


1 - Negative 
0 - Positive 


6-15 Notused 


Vertical total (Port l2E8h) Table 3-11 


Bit Function 


1-11 Vertical Total -The total number of half scan lines in the frame. 


12-15 Notused 


Vertical displayed (Port 16E8h) 
Table 3-12 


Bit Function 


1-11 Vertical Blank -The starting position of the vertical blank pulse 


in half scan lines. 


12-15 Notused 


Vertical sync start (Port lAE8h) 
Table 3-13 


Bit Function 


1-11 Vertical sync pulse 


12-15 Notused 


Vertical sync width (Port lEE8h) 
Table 3-14 


Bit Function 


1-4 Vertical sync width 


5 Vertical sync 


Polarity 
1 - Negative 
0 - Positive 


6-15 Notused 


The DAC register set includes ports 2EAh, 2EBh, 2Ech, and 2EDh. 
These registers include: DAC Mask, DAC Read Index, DAC Write 
Index, and DAC Data. All four registers contain eight bits of 
information. The 8514/A ANDs the bit stream with the contents DAC 
Mask register before sending them to the palette. This allows you to 
remove one or more bit planes from the data stream prior to display. 
The DAC Read Index addresses data at a specific address for the host. 


Table 3-15 


Use this register in combination with the DAC Data register (port 
2EDh) to read a palette location. The DAC Write Index addresses a 
specific palette location for writing. The host uses the DAC Data 
register to place information at the specified palette location. 


The control register set consists of ports 22E8h, 42E8h, 46E8h, 
4AE8h, and 9AE8h. This includes the Display Control, Subsystem 
Status, Subsystem Control, ROM Page Select, Advanced Function 
Control, Graphics Processor Status, and Command registers. Each 
register controls a different area of 8514/A operation. Tables 3-15 
through 3-19 describe the display elements controlled by each 
register. Note that you can read the Subsystem Status and Graphics 
Processor Status registers. The Subsystem Control and Command 
registers are write-only. 


Display control register (Port 22E8h) 


Bit Function 


0 Nugget phase Enable (Not used on some 8514/A implementations.) 


1-2 Pre-Scaler Bits 


00 - Divide NCLK by 2 (Pseudo 8-Plane Mode) 
01 - Divide NCLK by 4 (Standard 8514/A) 
10 - Divide NCLK by 6 (Not Used) 
11 - Divide NCLK by 8 (Not Used) 


Double Scan Select 
1 - Display each scan line once (normal). 
0 - Display each scan line twice. 


Interlaced Sync Select 
1 - Interlaced Sync 
0 - Non-Interlaced Sync 


5-6 DisplayEnable 


11 - Disable HSYNC, VSYNC, and BIANK* 
10 - Disable HSYNC, VSYNC, and BIANK* 
01 - Enable HSYNC, VSYNC, and BIANK* 
00 - Not Used 


7-15 Notused 


* Not Function (Setting bit disables input or output.) 


Subsystem status/control register (Port 42E8h) Table 3-16 


Bit Function 


Read - Subsystem Status 


0-3 IRQ -Interrupt Request (Determines state of interrupt request lines.) 


1XXX - Idle. The 8514/A is idle and waiting for input. This bit provides the same 
information as the BSY bit of the Queue Status Register. 
XIXX - Queue Overflow/Under flow. The host attempted to write to a full write 
queue or read from an empty read queue. 
XXIX - Inside Scissor Rectangle. The 8514/A drew current object within an area 
bounded by a scissor rectangle. You can use this bit to determine when two objects 
coincide. 
XXX1 - Vertical Blanking Active. Shows when it is safe to send data to the 
8514/A for display. 


4-6 Monitor sense -Determines type monitor attached to 8514/A. 


000 - Reserved 
001 - 8507 (1024 X 768 Interlaced Monochrome) 
010 - 8514 (1024 X 768 Interlaced Color) 
011 - Reserved 
100 - Reserved 
101 - 8503 (640 X 480 Non-Interlaced Monochrome) 
110 - 8512/8513 (640 X 480 Non-Interlaced Color) 
111 - Reserved 


8-Bit Plane Select (8BP) 
0 - 4 Bit Planes 
1 - 8 Bit Planes 


8-15 Not used 


W:rite - Subsystem Control 


0-3 IRQ clear -Interrupt Request (Write 1 to clear flag.) 


1X - Idle. 
XIXX - Queue Overflow/Under flow. 
XXIX - Inside Scissor Rectangle. 
XXX1 - Vertical Blanking Active. 


8-11 IRQ Enable -Interrupt Request (Write 1 to enable flag.) 


1XX - Idle. 
XIXX - Queue Overflow/Under flow. 
XXIX - Inside Scissor Rectangle. 
XXX1 - Vertical Blanking Active. 


12-13 Memory controller Disable 


00 - No Effect 
01 - Enable synchronization with memory controller chip. 
10 - Disable synchronization from memory controller chip. (8514/A does not 
operate correctly.) 


Table 3-16 Continued 


i--i_-:--.:_::i:.i- 


Bit Function 


11 - Disable synchronization from memory controller chip. (8514/A does not 
operate correctly.) 


14-15 Graphics processor Reset 


00 - No Effect 


95 : E::g[ec::js$ 
11 - Reset Chip 


ROM Page select register (Port 46#8h) 


Bit Function 


0-2 ROM page Number-Remaps one of eight 4 KByte ROM 


pages into the address area from C0000h - C5FFFh. 


3-15 Notused 


Table 3-18 
Advanced function control register (Port 4AE8h) 


Bit Function 


0 Advanced Function Mode select 


0 - VGA drives video connector. 
1 - 8514/A drives video connector. 


1 Not used 


2-4 Clock select -Not used, SetTo 0 
5-7 Notused 


Table 3-19 
Graphics processor status/command 


registers (Port 9EE8h) 


Bit Function 
Read - Graphics Processor Status Register 
0-7 Queue Full status 


00000000 - 8 Words Available (Queue Empty) 
00000001 - 7 Words Available 
00000011 - 6 Words Available 
00000111 -5 Words Available 
00001111 -4 Words Available 


Bit 
Function 


00011111 -3 Words Available 
00111111 -2 WordsAvailable 
01111111 -1 WordsAvailable 
11111111 - 0 Words Available (Queue Full) 


Variable Data Ready 
0 - Data Not Ready 
1 - Data Ready to Read from Data Register 


Busy 
0 - 8514/A Not Busy 
1 - 8514/A Executing a Drawing Command 


10-15 Notused 


Write - Command Register 


Pixel Write Operation 
0 - Write disabled. Rectangle commands copy rectangular blocks from bitmap to 
system memory. 
1 - Write enabled. Rectangle commands copy rectangular blocks from system 
memory to bitmap. 


Across Planes 
0 - Through Plane Mode 
1 - Across Plane Mode 


Last Pixel Null 
0 - 8514/A draws last pixel for line and SVV commands. 
1 - 8514/A moves current position pointer without drawing pixel. Use this with 
commands that produce the wrong pixel color on the last pixel of a row. For 
example, XOR. 


Short Stroke Enable 
0 - Short stroke vectors not enabled. 
1 - Short stroke vectors enabled. 8514/A draws contents of SSV register after 
each data write. 


Marking Enable 
0 - Marking disabled for line and BITBLTS (bit block transfers). 8514/A moves 
current position without changing pixels. 
1 - Marking enabled. 


Increment X Positive 
0 - 8514/A draws lines in X negative direction (right). 
1 - 8514/A draws lines in X positive direction (left). 


Y Major Axis 
0 - X is major (independent) axis for Bresenham algorithm. 
1 - Y is major (independent) axis for Bresenham algorithm. 


Increment Y Positive 
0 - 8514/A draws lines in Y negative direction (up). 
1 - 8514/A draws lines in Y positive direction (down). 


Table 3-19 Continued 


Bit Function 


8 Variable Data Enable 


0 - 8514/A draws normally. 
1 - 8514/A waits for read/write of variable data from host. 


9 16-bit operation (16B) 


0 - SSV and VAR are accessed as 8-bit registers. 
1 - SSV and VAR are accessed as 16-bit registers. 


10 Read Byte swap (RES) -8514/A reads bytes in opposite order written. 


RBS & 168 = 0 - No Swap 
RES & 168 = 1 - Swap 


11 Always set to zero. 


12 Byte order (Does not affect 16-bit registers.) 


0 - Read high byte first. 
1 - Read low byte first. 


13-15 Draw command 


000 - No Operation 
001 - Line 
010 - Fill rectangle in X direction. 
011 - Fill rectangle in Y direction. 
100 - Fast filled rectangle. 
101 - Outline 
110 -Copy Rectangle 
111 - Illegal (Generates error IRQ.) 


The graphics register set includes position, status, and control 
registers. The position registers consist of Current X Position (port 
82E8h), Current Y Position (port 86E8h), Destination X Position 
(port 8AE8h), and Destination Y Position (port 8EE8h). Each of these 
ports contain a number representing the start and finish of a graphics 
operation. The Y Position register contains a 10-bit number; all other 
registers contain 11-bit numbers. 


The status registers consist of Error Term (port 92E8h) and Major Axis 
Pixel Count (port 96E8h). The Error Term register contains a 12-bit 
number used as a constant for the Bresenham algorithm. The host must 
place a number equal to 2 x dy - dx in the register before starting the 
algorithm. The 8514/A automatically updates the register as it draws. 
The Major Axis Pixel Count register contains a 10-bit number. The 
8514/A uses this number for CopyRect commands and as the constant 
dx term for the Bresenham algorithm. You must use a positive number 
for dx. The 8514/A automatically updates this register. 


Finally, the control registers consist of Short Stroke Vector Transfer, 
Background Color, Foreground Color, Write Mask, Read Mask, Color 
Compare, Background Mix, Foreground Mix, Multi-Function Control, 
and Pixel Data Transfer. Table 3-20 contains a bit description of the 
Short Stroke Vector Transfer Register (port 9EE8h). Notice that you 
can write two SSVs at once in 16-bit mode. The Background Color 
(port A2E8h) and Foreground Color (port A6E8h) registers contain 8- 
bit numbers. The 8514/A uses the contents of the Background Color 
register for writing pixels if you select Foreground Color Mix and 
FSS=00 or select the Background Color Mix and BSS=00. Likewise, 
it uses the contents of the Foreground Color register for writing 
pixels if you select the Foreground Color Mix and FSS=01 or select 
the Background Color Mix and BSS=01. The Write Mask register 
(port AAE8h) contains 8 bits-one for each plane. Placing a 1 in a 
bit allows writing to that plane's bit. Bit 0 corresponds to plane 0. 


Short stroke vector (SSV) transfer register (Port 9EE8h) 
Table 3-20 


Bit Function 
0-3 Length -The number of pixels that the 8514/A moves the current position 


pointer. If length contains 0, the 8514/A does not change Current Position. 


4 Mark pixels 


0 - Move Current Position, but do not mark vector. 
1 -Markpixels 


5-7 Direction 


000 
001 
010 
011 
100 
101 
110 
111 


8-11 Length -The number of pixels that the 8514/A moves the current position 


pointer. If length contains 0, the 8514/A does not change Current Position. 


12 Mark pixels 


0 - Move Current Position, but do not mark vector. 
1 -Markpixels 


13-15 Direction 


000 - 00 
001 - 450 
010 - 900 


Table 3 -20 Continued 


Bit Function 


Table 3-21 


The Read Mask register (port AEE8h) contains 8 bits, one for each 
plane. Placing a 0 in a bit allows reading of the selected plane's bit. Bit 
0 corresponds to plane 0. The Color Compare register (port 82E8h) 
contains an 8-bit color number. The 8514/A compares the value of 
this color to the value of the destination during BITBLT operations. If 
the comparison is true, the CPU changes the destination. The 
comparison can use any type of equality including greater-than and 
less-than. The 8514/A uses the contents of bits 3, 4, and 5 of the 
Pixel Control register (port BEE8 index A) to control the comparison 
type. The 8514/A uses the contents of the Background Mix (port 
86E8h) and Foreground Mix (port BAE8h) registers to control display 
color during drawing operations. This includes selection of both the 
mix color source and mix method. The Pixel Control register controls 
the selection of either the Foreground Mix or Background Mix register. 
Tables 3-21 and 3-22 describe these two registers. 


Background mix register (Port 86E8h) 


Bit Function 


0-5 MixMethod 


00000 - -DST 
00001 - 0 (Destination always false.) 
00010 - 1 (Destination always true.) 
00011 - DST 
00100 - -SRC 
00101 - SRC ^ DST 
00110 - ~ (SRC ^ DST) 
00111 - SRC 
01000 - ~ (SRC * DST) 
01001 - ~ (SRC * ~DST) 
01010 - ~ (~SRC * DST) 
01011 - ~ (~SRC * ~DST) 
01100 - SRC * DST 
01101 - SRC * ~DST 
01110 - ~SRC * DST 


Bit Function 


5-7 


Legend.. 


DST 
SRC 


01111 - ~SRC * ~DST 
10000 - min(SRC,DST) 
10001 - DST - SRC Ovith Under flow) 
10010 - SRC - DST Ovith Under flow) 
10011 - SRC + DST Ovith Overflow) 
10100 - max(SRC,DST) 
10101 - (DST -SRC)/2 Ovith Under flow) 
10110 - (SRC -DST)/2 Ovith Under flow) 
10111 - (SRC + DST)/2 Ovith Overflow) 
11000 - DST -SRC Ovith Saturate) 
11001 - DST -SRC Ovith Saturate) 
11010 - SRC -DST Ovith Saturate) 
11011 - SRC + DST Ovith Saturate) 
11100 - (DST -SRC)/2 Ovith Saturate) 
11101 - (DST -SRC)/2 Ovith Saturate) 
11110 - (SRC -DST)/2 Ovith Saturate) 
11111 - (SRC + DST)/2 Ovith Saturate) 


Background Source Select 
00 - Background Color Register Contents 
01 - Foreground Color Register Contents 
10 - Variable Data 
11 - Bitmap Data 


Destination 
Source 
Not 
XOR 
And 
Numeric Addition 
Numeric Subtraction 
Integer Division 


Foreground mix register (Port BAE8h) 


Bit Function 


0-5 MixMethod 


00000 
00001 
00010 
00011 
00100 
00101 
00110 


-DST 
0 (Destination always false.) 
1 (Destination always true.) 
DST 
-SRC 
SRC ^ DST 
~ (SRC ^ DST) 


Table 3-22 Continued 


:::--_: --:-_I -- 


Bit Function 


5-7 


00111 - SRC 
01000 - ~ (SRC * DST) 
01001 - ~ (SRC * ~DST) 
01010 - ~ (~SRC * DST) 
01011 - ~ (~SRC * ~DST) 
01100 - SRC * DST 
01101 - SRC * ~DST 
01110 - ~SRC * DST 
01111 - ~SRC * ~DST 
10000 - min(SRC,DST) 
10001 - DST -SRC With Under flow) 
10010 - SRC -DST With Under flow) 
10011 - SRC + DST Ovith Overflow) 
10100 - max(SRC,DST) 
10101 - (DST -SRC)/2 Ovith Under flow) 
10110 - (SRC -DST)/2 Ovith Under flow) 
10111 - (SRC + DST)/2 Ovith Overflow) 
11000 - DST -SRC Ovith Saturate) 
11001 - DST -SRC Ovith Saturate) 
11010 - SRC -DST Ovith Saturate) 
11011 - SRC + DST Ovith Saturate) 
11100 - (DST -SRC)/2 Ovith Saturate) 
11101 - (DST -SRC)/2 Ovith Saturate) 
11110 - (SRC -DST)/2 Ovith Saturate) 
11111 - (SRC + DST)/2 Ovith Saturate) 


Foreground Source Select 
00 - Background Color Register Contents 
01 - Foreground Color Register Contents 
10 - Variable Data 
11 - Bitmap Data 


Destination 
Source 
Not 
XOR 
And 
Numeric Addition 
Numeric Subtraction 
Integer Division 


The Multi-Function Control register (port BEE8h) provides multiple 
services. You access each service by using an index number as part of 
the input. In all cases, bits 12 through 15 contain the index number. 


Index 0 accesses the Minor Axis Pixel Count register. This register 
contains an 11-bit number that determines the rectangular height for 
BITBLTs. The next four indexes (1 through 4) control the scissors 
registers. The Top Scissors register (index 1) determines the upper limit 
of the boundary. The Left Scissors register (index 2) determines the 
minimum X limit of the boundary. The Bottom Scissors register (index 
3) determines the lower limit of the boundary. Finally, the Right Scissors 
register (index 4) determines the maximum (right) X limit of the 
boundary. Each register contains a 12-bit number. Each time the 
8514/A draws an object within the boundary described by these four 
registers, it outputs an interrupt (when enabled). The Memory Control 
register (index 5) determines the physical configuration of memory on 
the adapter. Table 3-23 describes the bit contents of this register. The 
Pattern X and Pattern Y registers (index 8 and 9) mix colors on a pixel- 
by-pixel basis. The Pattern X register contains the mix for even- 
numbered nuggets (four bits per plane) and the Pattern Y register 
contains the mix for odd numbered nuggets. Each register uses bits 1 
through 4 to provide the mix pattern. Bit 4 controls pixel 0. The Pixel 
Control register (index A) determines the color mix modes and methods 
logic. Table 3-24 describes each bit in this register. 


Memory control register (Port BEE8h Index 5) 
Table 3-23 


Bit Function 


2-3 


5-11 


12-15 


Not Used 


X Coordinate Divisor - Determines the memory bank interleave factor in a 
horizontal direction. 
0 - 1 Bank, No Interleave 
1 - 2 Horizontally Interleaved Banks (Normal) 


Y Coordinate Divisor - Determines the memory bank interleave factor in a vertical 
direction. 
00 - 2 banks of 256 Kbyte VRAM. Extended modes, no pseudo 8-plane mode. 
01 - 4 banks of 256 Kbyte or 1 bank of 1 Mbyte VRAM. 8514/A compatible 
modes. 
10 - 2 banks of 1 Mbyte VRAM. Extended modes. 
11 - 4 banks of 1 Mbyte VRAM. Extended modes. 


SWP -Active in Pseudo 8 Plane Mode (Always Set to 0 When Not in Use.) 
0 - Select buffer number zero, lower four planes. 
1 - Select buffer number one, upper four planes. 


Not Used 


Index - Always Equals 5 


Table 3-24 
Pixel control register (Port BEE8h lndesx Ah) 


Bit Function 


0 Not used 


1 MOD1 


0 - Normal Operation 
1 - Disables mixes. Opposite polarity of MOD2. 


3-5 


6-7 


MOD2 
0 - Normal Operation 
1 - Disables mixes and prevents VRAM RMW cycles if bits 3 through 
5 equal zero. 


Color Comparison 
000 - Always False 
001 -Always True 
010 - DST >= CCMP 
011 - DST < CCMP 
100 - DST = CCMP 
101 - DST = CCMP 
110 - DST <= CCMP 
111 - DST > CCMP 


Foreground Select 
00 - Foreground Mix register is always used. 
01 - PAIX and PATY select mix (1 equals Foreground Mix register). 
10 - Variable data selects mix (1 equals Foreground Mix register). 
11 - SRC selects mix (used to implement transparency). 


8-11 Not used 


12-15 Index -Always Equals 10 


Legend, 


DST Destination 
SRC Source 
CCMP Color comparison 


-*- TMS340JT0 Graphics System Processor (GSP) TMS340xO 


Graphics System Processor (GSP) programming requires three 
pieces of information. First, the programmer must know the memory 
mapping used by the interface software/ROM to provide access to 
the GSP. Second, the programmer must know how to use the 
registers provided by the GSP to manipulate data in program and 
display memory. Some vendor boards do not allow direct access to 
either memory area. To read or write host data, you first must 
program the register set, then use processor commands to initiate the 
transfer. Third, the programmer must know the GSP instruction set. 


Refer to the vendor manual for your GSP to obtain the addresses of 
various GSP components. You can eliminate this requirement by 
using the TIGA interface. The following paragraphs describe both the 
GSP registers and instruction set. Figure 3-2 shows a typical 
TMS34010 implementation. Notice that the block diagram looks 
similar to the other display implementations. The big difference is the 
graphics processor provided with this setup. The programmability of 
the GSP adds to the functionality provided by this system. The 
block diagram shows a generalized version of a typical GSP 
implementation. Most manufacturers deviate from this basic design. 


34010 Processor 


Typical 30410 block diagram. 


The TMS340xO GSP contains four sets of registers: general-purpose, 
special-purpose, input/output, and memory-control. Each register set 
performs a specific task and contains more than one register. The 
general-purpose registers work with the execution unit to manipulate 
data. The special-purpose registers contain CPU execution flags and 
settings. The input/output registers provide an interface between the 
GSP, host, and external display related devices. The memory-control 


Table 3-25 


registers affect the internal memory operations of the GSP. The 
following paragraphs describe the registers in detail. 


The general-purpose registers consist of two banks of 15 registers (30 
total registers). You refer to the first bank as Register File A and the 
second bank as Register File 8. The GSP does not use Register File A 
for any special purpose. Therefore, you can use Register File A to 
store any semi-permanent variables. The GSP does use Register File 
8 for special purposes. This includes PIXBLT and line drawing 
operations. Table 3-25 describes the special uses for Register File 8. 
Always load Register File 8 with the required information before 
executing a line drawing or PIXBLT operation. When not in use, 
Register File 8 reacts exactly like Register File A. In addition to 
standard registers, each register file contains a stack pointer (SP). The 
340xO locks the two stack pointers together, meaning that the GSP 
provides one physical SP. The reason that each register file contains 
a reference to SP is to reduce the number of clock cycles required to 
perform a task. You can use SP like any other general register. 


TMS34010 register file 8 functions 


Register Function 


80 Source Address (SADDR) -Contains a linear or xY address describing the 


upper left corner (lower address in array) of the source pixel array. 


81 


82 


83 


84 


85 


86 


87 


88 


Source Pitch (SPTCH) - The distance between adjacent rows of the source 
pixel array. 
Destination Address (DADDR) - Contains a linear or XY address describing the 
upper left corner (lower address in array) of the destination pixel array. 


Destination Pitch (DPTCH) - The distance between adjacent rows of the 
destination pixel array. 


Offset (OFFSET) -Linear address of the XY coordinate origin 0{ = 0, Y = 0). 
The GSP uses this address during XY to linear address conversions. 


Window Start Address (WSTART) - An address describing the upper left corner 
(lowest address) of the window area. 


Window End Address (WEND) - An address describing the lower right corner 
(highest address) of the window area. 


Delta X/Delta Y (DYDX) -Two 16-bit numbers describing the width (DX) and 
height (DY) of the destination array. The MSB holds DY, while the LSB holds DX. 


Color 0 (COLORO) -The 16 MSB bits contain the background color used for 


Register Function 


fill, color expand, or draw and advance operations. The 16 LSB bits contain all 
ones or a pattern of ones and zeros for dithered output. The 34010 ignores 
the 16 MSB bits during color expand operations. 


89 


810-814 
(PIXBLT) 
810 


Color 1 (COLOR1) -The 16 MSB bits contain the foreground color used for 
fill, color expand, or draw and advance operations. The 16 LSB bits contain all 
ones or a pattern of ones and zeros for dithered output. The 34010 ignores 
the 16 MSB bits during color expand operations. 


Temporary Storage (TEMP) - Contain temporary information during PIXBLT 
operations. 


Count (COUNT) - Contains the number of pixels drawing during a line draw 


(Line Draw) operation. 


811 Increment 1 (INC1) -Contains the x and Y values for a diagonal step. 
(Line Draw) 


812 Increment 2 (INC2) -Contains the x and Y values for a non-diagonal step. 
(Line Draw) 


813 Pattern (PATTRN) -Future Expansion. Always set this register to oFFFFFFFFh 
(Line Draw) (all ones) before performing a line draw operation. Failure to do so will result in 


software compatibility problems. 


SP Stack pointer -Points to the top (lowest address) of the stack. 


There are three special-purpose registers: status, program counter, 
and instruction cache. Each special-purpose register is 32 bits long. 
The status register (ST) contains information about CPU status. Table 
3-26 describes the status information contained in this register. The 
program counter (PC) points to the next instruction in the execution 
sequence. The GSP aligns all instructions on 16-bit boundaries. 
Therefore, the four LSB bits of this register always contain 0. An 
instruction can consist of more than one instruction word. As the 
GSP retrieves each instruction word, it automatically updates PC. 
There are occasions when the GSP replaces the contents of PC with 
another value. Table 3-27 describes each occurrence. 


34010 status register 
Table 3-26 


Bit Function 
0-4 
Field Size 0 (FSO) -Length of the first data field in bits. A field size of OOoolb 
corresponds to a 1-bit field length. A field size of 11111b corresponds to a 31-bit 
field length. A field size of OOOoob corresponds to the maximum field length of 
32 bits. 


Table 3-2 6 Continued 


Bit Function 


5 Field Extend o (FEO) -Determines method of extending field o when loaded into a 


32-bit register. 
0 - Zero extend field. 
1 - Sign extend field. 


6-10 Field size 1 (FS1) -Length of the second data field in bits. A field size of oooolb 


corresponds to a 1-bit field length. A field size of 11111b corresponds to a 31-bit 
field length. A field size of OOOoob corresponds to the maximum field length of 
32 bits. 


11 
Field Extend 1 (FE1) - Determines method of extending field 1 when loaded into a 
32-bit register. 
0 - Zero extend field. 
1 -Sign extend field. 


12-20 Notused 


21 Interrupt Enable (IE) 


0 - Disables all maskable interrupts. 
1 - Enables all maskable interrupts. 


22-24 Notused 


25 PIXBLT Executing (PBX) -Indicates if an interrupt occurred in the middle of a 


PIXBLT or FILL instruction. 
0 - Interrupt occurred at PIXBLT or FILL instruction boundary. 
1 - Interrupt occurred in the middle of a PIXBLT or FILL instruction. 


26-27 Notused 


28 


29 


30 


31 


Overflow Flag ov) - Set according to instruction execution parameters. 


Zero Flag (Z) - Set according to instruction execution parameters. 


Carry Flag (C) - Set according to instruction execution parameters. 


Negative Flag (N) - Set according to instruction execution parameters. 


34010 program counter replace values 


Type 


Standard Instructions 
(Non-Branch) 


Absolute Branch To 
Instruction Address 
(TRAP, CALL, JAx) 


GSP Replace Value 


GSP increments PC by 16 (10h) after each instruction word retrieval. 
Execution proceeds with the next instruction in sequence. 


GSP loads specified address (instruction word contents after 
instruction). It automatically zeros four LSB bits. Execution proceeds 
with instruction pointed to by PC. 


Type 


Relative Branch To 
Instruction Address 
(jFdr, Dsjx) 


Indirect Branch To 
Register Address 
(JUMP, EXGPC) 


GSP Replace Value 


GSP shifts instruction offset by four bits to zero four LSB bits. It adds the 
offset to PC. Execution proceeds with instruction pointed to dy PC. 


GSP loads PC with register contents. It automatically zeros four LSB 
bits. Execution proceeds with instruction pointed to by PC. 


The instruction cache is 256 bytes long. It contains four segments. Each 
segment provides access to 64 bytes of cache memory. The segments 
are further broken down into 8 subsegments (also called data registers). 
Each subsegment contains 8 bytes (four 16-bit words) of code or data. 
The GSP aligns each segment on an even 32-bit word boundary. It 
addresses each word within the segment, as shown in Table 3-28. The 
GSP provides access to the cache register pointed to by PC. A program 
cannot read the contents of any of the other cache registers. 


34010 instruction cache segment 


start address (SSA) format 


Table 3-28 


9-31 


Contentsrvalue 


Always set to zero. 


Instruction word address within subsegment. 
00 - First Word 
01 -Second Word 
10 -Third Word 
1 1 - Fourth Word 


Subsegment address within segment. 
000 - Subsegment 1 
001 -Subsegment 2 
010 -Subsegment 3 
011 -Subsegment 4 
100 -Subsegment 5 
101 -Subsegment 6 
110 -Subsegment 7 
1 1 1 - Subsegment 8 


Segment Start Address (SSA). 
Corresponds to segment address in main memory. 


The instruction cache uses a least-recently used algorithm to replace 
the contents of the cache. Each time the GSP requests a segment not 
currently in memory, the cache controller fetches a new 64-byte 


Table 3-29 


segment from main memory. It replaces the least-recently used 
segment with the new segment contents. 


The input/output register affects most display parameters used by the 
340xO. Both the host and 340xO can access the input/output 
register. There are 28 different input/output registers. As shown in 
Table 3-29, a program can access a register by name or address. The 
host accesses the registers through the host interface registers. It 
does this by loading the input/output register address in HSTADRL 
and HSTADRH registers. It then reads or writes the contents of the 
HSTDATA register. These registers occupy the address range from 
C0000000h to C00001FFh. 


34010 input/output registers 


Address Register 


C0000170h- RESERVED 
C00001A0h 


Host Interface Registers 


C00000C0h HSTDATA 


C00000D0h HSTADRL 


Function 


These register addresses reserved for future expansion. 


Host Interface Data - A buffer used to transfer data between 
the host and the 34010 local memory. 


Host Interface Address Low Word - This register contains the 
16 LSB bits of the local memory address accessed by the 
host computer. Local memory addresses include register 
addresses. 


C00000E0h HSTADRH Host Interface Address High word -This register contains 


the 16 MSB bits of the local memory address accessed by the 
host computer. Local memory addresses include register 
addresses. 


C00000F0h HSTCTLL Host Interface control Low Byte -Controls host interface 


functions as shown below. 
Bit Functio n 


0-2 Input Message Buffer (MSGIN) 
3 Input Interrupt Bit (INTIN) 
4-6 Output Message Buffer (MSGOUT) 
7 Output Interrupt Bit (INTOUT) 
8-15 Reserved 


C0000100h HSTCTLH Host Interface control High Byte -Controls host interface 


functions as shown below. 


Address Register Function 


Bit Function 


0-7 Reserved 
8 Nonmaskable Interrupt (NMI) 
9 NMI Mode Bit 
10 Reserved 
11 Increment pointer Address on write (INCW) 
12 Increment pointer Address on Read (INCR) 
13 LowerByte Last(LBL) 
14 CacheFlust(CF) 
15 Halt 34010 Execution (HLT) 


Local Memory Interface Registers 


C00000B0h CONTROL Memory control -Controls local memory interface 


operations as shown below. 


Bit Function 


0-1 Reserved 
2 DRAM Refresh Mode (RM) 
3-4 DRAM Refresh Rate (RR) 
5 Transparency Enable (T) 
6-7 Window violation Detection Mode (W) 
8 PIXBLT Horizontal Direction (PBH) 
9 PIXBLT vertical Direction (PBV) 
10-14 Pixel processing operation select (PPOP) 
15 Cache Disable (CD) 


C0000130h CONVSP 
Source Pitch Conversion Factor -Used by 34010 during XY 
to linear conversion of a source memory address. 


C0000140h CONVDP Destination pitch conversion Factor -Used by 34010 during 


XYAinear conversion of a memory address. 


C0000150h PSIZE 


C0000160h PMASK 


C00001 F0h REFCNT 


Pixel Size Register - Specifies the pixel size in bits. Possible 
sizes include 1, 2, 4, 8, and 16 bits (2, 4, 16, 256, and 
65,536 colors). 


Plane Mask Register - Enables/disables bits in the bit map 
plane. For example, setting bit 0 to 1 enables bit plane 0. 


Refresh Count Register - Generates the addresses output 
during DRAM refresh cycles and counts delay between next 
refresh eycles. 


B it Function 


0-1 Reserved 
2-7 Refresh Interval counter (RINTVL) 
8-15 Row Address (ROWADR) 
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Addres s Register 


Interrupt Control Registers 
C0000110h INTENB 


Function 


Interrupt Enable - Selectively enables or disables three 
internal and two external interrupts as shown below. 
Bit Function 


0 Reserved 
1 External Interrupt 1 Enable (XIE) 
2 External Interrupt 2 Enable o{2E) 
3-8 Reserved 
9 Host Interrupt pending (HIP) 
10 Display Interrupt pending (DIP) 
11 Window violation Interrupt pending (WVP) 
12-15 Reserved 


C0000120h INTPEND Interrupt pending -Shows which interrupts are pending 


using the same bit mask as INTENB. 


Video Timing and Refresh Fzegisters 


C0000000h HESYNC Horizontal End sync -Contains the ending value of the 


horizontal sync interval. 


C0000010h HEBLNK Horizontal End Blank -Contains the ending value of the 


horizontal blank interval. 


C0000020h HSBLNK Horizontal start Blank -Contains the starting value of the 


horizontal blank interval. 


C0000030h HTOTAL Horizontal Total -Contains the total value of the horizontal 


scan line in VCLK periods. 


C0000040h VESYNC Vertical End sync -Contains the ending value of the vertical 


sync interval. 


C0000050h VEBLNK Vertical End Blank -Contains the ending value of the vertical 


blank interval. 


C0000060h VSBLNK Vertical start Blank -Contains the starting value of the 


vertical blank interval. 


C0000070h VTOTAL Vertical Total -Contains the total value of the vertical scan 


line in VCLK periods. 


C0000080h DPYCTL Display control -Controls several video timing signal values 


as shown below. 
Bit Function 


0 Horizontal sync Direction (HSD) 
1 Reserved 
2-9 Display Address update (DUDATE) 
10 Screen origin select (ORG) 


Address Register Function 


Bit Function 


11 VRAM serial Register Transfer Enable (SRT) 
12 Screen Refresh Enable (SRE) 
13 Disable External video (DXV) 
14 Noninterlaced video Enable (NIL) 
15 Enablevideo(ENV) 


C0000090h DPYSTRT Display start Address -Controls the automatic memory-to- 


register cycles required to refresh a screen as shown below. 
Bit Function 


0-1 Specifies the number of scan lines displayed between 


refresh cycles. (LCSTRT) 


2-15 Starting screen-Refresh Address. (SRSTRT) 


C00000A0h DPYINT Display Interrupt -Contains the number of the next scan line 


which causes a display interrupt request. 


C00001B0h DPYTAP Display Tap point Address -Used during shift register 


transfer cycles. Contains a VRAM tap point address. 


C00001C0h HCOUNT Horizontal count -Contains the number of VCLK cycles per 


horizontal scan line. 


C00001D0h VCOUNT Vertical count -Contains the number of horizontal scan lines 


in a display. 


C00001E0h DPYADR Display Address -Counts the number of scan lines output 


between screen refresh cycles. Also contains the source of 
the row and column addresses output during a screen refresh 
cycle as shown below. 
Bit Function 
0-1 Scan Line counter (LNCNT) 
2-15 Screen Refresh Address (SRFADR) 


Each of the registers shown in Table 3-29 fall into one of four 
groups. Each group performs a specific task. The host interface 
registers provide host to 340xO communications. The host computer 
performs most communication with the display adapter through this 
interface. The local memory-control register controls how the 340xO 
manipulates data in VRAM. This includes the size of various display 
adapter constructs like pixel depth and window size. The interrupt- 
control register provides status information to the 340xO and host 
computer. The host computer can perform display-related tasks more 
efficiently by monitoring these two registers. The physical 
characteristics of the display adapter and display mode affect the 
video timing and screen refresh registers. 


Table 3-30 


In addition to registers, the 340xO uses the instruction set 
summarized in Table 3-30. Notice that this instruction set contains 
instructions specifically designed for display data manipulation. Also, 
note that, although Texas Instruments optimized the 340xO for 
graphic operations, it also uses generalized instructions like jump. 
This differentiates the 340xO from both a standard display adapter 
BIOS or coprocessor and a general-purpose processor like the 8088. 
The 340xO can perform any task performed by a general-purpose 
processor. This gives it display data manipulation capabilities not 
found in standard display adapter BIOS or coprocessor chips. 


34010 instruction set 


Instruction Type 


AB S Arithm eti c 


ADD Arithmetic 


ADD C Arithmetic 


ADDI Arithmetic 


ADDK Arithmetic 


AD DXY Arithmetic 


AND Logical 


ANDI Logical 


ANDN Logical 


ANDNI Logical 


BTST Compare 


CALL 


CALIA 


Program 
Control and 
Context 
Switching 


Function 


Stores the absolute value of a number in a destination register. 


Adds the source register to the destination register. 


Adds the source register to the destination register and sets 
the carry flag if necessary. 


Adds an immediate value to the destination register. The 
immediate value may be 16 or 32-bits long. 


Adds a 5-bit constant to the destination register. 


Adds the source register to the destination register in XY mode. 


Performs a logical AND of the value in the destination register 
with the source register. 


Performs a logical AND of the value in the destination register 
with a 32-bit immediate value. 


Performs a logical AND of the value in the destination register 
with the source register, then complements the result. 


Complements a 32-bit immediate value, then performs a 
logical AND of the value in the destination register with the 
32-bit immediate value. 


Tests the bit specified by a constant or source register in the 
destination register. 


Calls the subroutine address placed in the source register. 


Program Calls the absolute subroutine address specified by an 
Control and immediate value. 


Instruction Type 


CALLR 


Function 


Context 
Switching 


Program Calls the relative subroutine address specified by an 
Control and immediate value. 
Context 
Switching 


CLR Compare 


CLRC Compare 


CMP Compare 


C MPI Compare 


CMPXY Compare 


CPW Graphics 


CVXYL Graphics 


DEC Arithmetic 


D INT Program 


Control and 
Context 
Switching 


DIVS Arithmetic 


DIVU Arithmetic 


D RAV Graphics 


Clears the specified register. 


Clears the carry flag. 


Nondestructively compares the value in the source register to 
the destination register. Sets or clears the appropriate status 
bits. 


Nondestructively compares an immediate value to the 
destination register. Sets or clears the appropriate status bits. 
The immediate value may be 16 or 32-bits long. 


Nondestructively compares the X and Y half of a register. 
Sets or clears the appropriate status bits. 


Compares a point specified by an X and Y coordinate in the 
source register to the window limits in the WEND or 
WSTART registers. X and Y are 16-bit signed values. WEND 
and WSTART must contain positive values. Used to reject 
objects drawn outside the confines of a window. 


Convert an XY address to a linear address. 


Reduces the contents of the specified register by one. 


Disable maskable interrupts. 


Perform a signed division of the destination register by the 
source register. The 34010 performs the division on a 64-bit 
number if the destination register number is even (for 
example A14). Otherwise, it performs the division on a 
32-bit number. The source and destination registers must 
appear in the same register file. 


Perform an unsigned division of the destination register by 
the source register. The 34010 performs the division on a 
64-bit number if the destination register number is even (for 
example A14). Otherwise, it performs the division on a 
32-bit number. The source and destination registers must 
appear in the same register file. 


Draws a pixel at the address pointed to by the destination 
register using the color in COLOR1. The 34010 then adds 
the value in the source register to the destination register. 
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Instruction Type 


DSJ Jump 


DSJEQ Jump 


DSJNE Jump 


DSJS Jump 


EINT 


EMU 


EXGF 


EXGPC 


Program 
Control and 
Context 
Switching 


Function 


If the destination register is greater than 0, the 34010 
decrements it by one and advances to the specified address. 
Otherwise, it skips the jump and proceeds with the next 
sequential instruction. 


This instruction first checks to see if the zero flag (Z) is set. If 
Z = 1, then the 34010 skips the jump. Otherwise, if the 
destination register is greater than 0, the 34010 decrements 
it by one and advances to the specified address. Otherwise, it 
skips the jump and proceeds with the next sequential 
instruction. 


This instruction first checks to see if the zero flag (Z) is clear. 
If Z = 0, then the 34010 skips the jump. Otherwise, if the 
destination register is greater than 0, the 34010 decrements 
it by one and advances to the specified address. Otherwise, it 
skips the jump and proceeds with the next sequential 
instruction. 


If the destination register is greater than 0, the 34010 
decrements it by one. If the direction bit (D) equals 0, the 
34010 adds the specified value to the program counter. 
Otherwise, the 34010 subtracts the specified value from the 
program counter. If the destination register equals 0, the 
34010 skips the jump and proceeds with the next sequential 
instruction. 


Enable maskable interrupts. 


Program The 34010 enters emulation mode. This instruction is 
Control and intended for systems level programming only. 
Context 
Switching 


Program 
Control and 
Context 
Switching 


Program 
Control and 
Context 
Switching 


FILL L Graphics 


Exchanges the six LSB bits of the destination register with the 
specified field bits. The 34010 clears the upper 26-bits of the 
destination register. 


Exchanges the value contained in the destination register 
with the program counter. Program execution continues with 
the new program counter address. 


Fills a two dimensional array with the value contained in 
COLOR1. DADDR contains the pixel array starting address 


Instruction Type 


FILL XY 


GETPC 


GETST 


Function 


(linear value). DPTCH contains the pixel array pitch (linear 
value). DYDX contains the pixel array dimensions. 


Graphics Fills a two dimensional array with the value contained in 


COLOR1. DADDR contains the pixel array starting address 
O{Y value). DPTCH contains the pixel array pitch (linear value). 
OFFSET contains the address of the screen origin (linear 
value). WSTART contains the window starting address O{Y 
value). WEND contains the window ending address O{Y value). 
DYDX contains the pixel array dimensions. 


Program Increments the program counter value by 16 (to point past 
Control and the current instruction) and places the value in the destination 
Context register. 
Switching 


Program Copies the contents in the status register to the destination 
Control and register. 
Context 
Switching 


I N C Arithmetic 


JAcc Jump 


Increases the contents of the specified register by one. 


Jump to the specified address (absolute) if the status flag(s) 
listed below contain the correct values. 


cc NCZV NCZV NCZV 
8 XIXX 


C XIXX 


EQ XXIX 


GE 0XX0 1XX 1 


GT 0X00 1X01 


HI X00X 


HS X00X XXIX 
LE 0XX1 1X0 XIX 
LO XIX 
LS XIX XIX 
LT 0X1 1XX0 
NIX 
NB XOX 


NC XOXX 
NE XOX 


NN 0XXX 
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Instruction Type 


JRcc Jump 


JUMP Jump 


LINE [0,1] Graphics 


LMO Compare 


Function 


cc NCZV NCZV NCZV 


NV XXX0 


NZ XXOX 


P 0XOX 
UC Xrm 
VXI 


Z XXIX 


Add the specified value to the program counter (relative 
jump) if the status flag(s) listed below contain the correct 
values. 


cc NCZV NCZV NCZV 
CXIX 


GE 0XX0 1XXI 


GT 0X00 1X01 


HI X0 0X 


LE 0XX1 1XX0 XXIX 


LS XXIX XIXX 


LT 0X 1 1 XX0 
NIXX 


NC XOXX 
NN0X 
NV XX0 


NZ XXOX 


P 0XOX 
uc xxxx 
VXI 
ZXIX 


Perform an absolute jump to the specified address. 


Selects one of two available line drawing algorithms. 


Locates the leftmost 1 in the source register and places the 
1's complement of its location in the destination register (5 


Instruction Type 


MMFM M ove 


M MTM Move 


M O DS Arithmetic 


M ODU Arithmetic 


M OVB M ove 


MOVE Move 


M OVI M ove 


M OVK M ove 


M OVX M ove 


M OVY Move 


MPYS Arithmetic 


MPYU Arithmetic 


NEG Arithmetic 


Function 


LSB bits). If the source register does not contain a 1, the 
34010 loads the destination register with zeros and sets the 
zero flag. 


Moves the contents of memory to the specified register list. 
All registers in the list must appear in the same register file. 


Moves the contents of a specified register list to memory. All 
registers in the list must appear in the same register file. 


Returns the signed remainder of the division of the 
destination register by the source register. Both registers 
always contain a 32-bit number. Both registers must appear 
in the same register file. 


Returns the unsigned remainder of the division of the 
destination register by the source register. Both registers 
always contain a 32-bit number. Both registers must appear 
in the same register file. 


Moves a byte from the source register to the memory address 
pointed to by the destination register. Both registers must 
appear in the same register file. 


Moves the contents of the source register, source register 
address, or explicitly specified memory address to the 
destination register, the memory address pointed to by the 
destination register, or an explicitly specified memory 
address. 


Stores a 16-bit, sign extended or 32-bit immediate value in 
the destination register. 


Stores a 5-bit constant in the destination register. 


Moves the X half of the source register to the X half of the 
destination register. Does not affect the Y half of either 
register. Both registers must appear in the same register file. 


Moves the Y half of the source register to the Y half of the 
destination register. Does not affect the X half of either 
register. Both registers must appear in the same register file. 


Performs a signed multiplication of the source register by the 
destination register. The 34010 stores a 32-bit result if the 
destination register is odd. Otherwise, it stores a 64-bit result. 
Both registers must appear in the same register file. 


Performs an unsigned multiplication of the source register by 
the destination register. The 34010 stores a 32-bit result if 
the destination register is odd. Otherwise, it stores a 64-bit 
result. Both registers must appear in the same register file. 


Stores the 2s complement of the number in the destination 
register back into the destination register. 
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Instruction Type 


NEGB Arithmetic 


NOP Program 


Control and 
Context 
Switching 


NOT Logical 


OR Logical 


ORI Logical 


PIXBLTB, L Graphics 


PIXBLT B, XY Graphics 


PIXBLTL, L Graphics 


PIXBLT L, XY Graphics 


PIXBLT XY, L Graphics 


PIXBLT XY, XY Graphics 


PIXT Graphics 


POPST 


PUSHST 


Program 
Control and 
Context 
Switching 


Program 
Control and 


Function 


Stores the 2s complement of the number in the destination 
register back into the destination register. The 34010 
decrements the result by one if the borrow bit is set. 


The processor does not perform any instruction. The 
program counter is set to the next instruction. 


Stores the ls complement of the number in the destination 
register back into the destination register. 


Performs a logical OR of the source register with the 
destination register. Both registers must appear in the same 
register file. 


Performs a logical OR of an immediate value with the 
destination register. 


Pixel Block Transfers the contents of a binary pixel array to a 
linear array. 


Pixel Block Transfers the contents of a binary pixel array to 
an XY array. 


Pixel Block Transfers the contents of a linear pixel array to a 
linear array. 


Pixel Block Transfers the contents of a linear pixel array to 
an XY array. 


Pixel Block Transfers the contents of an XY pixel array to a 
linear array. 


Pixel Block Transfers the contents of an XY pixel array to an 
XY array. 


Transfers the contents of the source register to the address 
pointed to by the destination register. It can also transfer the 
contents of the address pointed to by the source register to 
the destination register. PSIZE determines the size of the 
pixel. The address contained in the source or destination 
register is either XY or linear. 


Pops the status register from the stack and increments SP 
by 32. 


Pushes the status register onto the stack and decrements SP 
by 32. 


Instruction Type 


Context 
Switching 


PUTST 


RETI 


RETS N 


REV 


RL 


Function 


Program Places the contents of the specified register into the status 
Control and register. 
Context 
Switching 


Program 
Control and 
Context 
Switching 


Program 
Control and 
Context 
Switching 


Program 
Control and 
Context 
Switching 


Shift 


SETC Compare 


SETF Program 


Returns to an interrupted routine from an interrupt service 
routine. ST and PC are popped from the stack and SP is 
incremented by 64. 


Returns to an interrupted routine from a subroutine. This 
return may contain an optional stack increment value 
(32 + 16N). If N is not specified, SP is incremented by 32. 


Returns the revision number of the TMS34010 installed on 
the display adapter. 


Rotate the value in the destination register left by the amount 
specified in a constant or the source register. 


Sets the carry bit of the status register to 1. 


Loads the field size and field extension values into the status 


Control and register. This does not affect the value of the flags. 
Context 
Switching 


SEXT Arithmetic 


SIA Shift 


SLL Shift 


SRA Shift 


Sign extends the right justified field of the destination register 
using the MSB of the field. 


Shifts the destination register field left by the value contained 
in a constant or the five LSB bits of the source register. The 
MSB of the destination register is always shifted to the carry 
bit of the status register. This instruction provides overflow 
detection and sets the overflow bit of the status register as 
required. 


Shifts the destination register field left by the value contained 
in a constant. The MSB of the destination register is always 
shifted to the carry bit of the status register. This instruction 
does not provide overflow detection. 


Shifts the destination register field right by the value 
contained in a constant or the five LSB bits of the source 
register. The LSB of the destination register is always shifted 
to the carry bit of the status register. This instruction provides 
overflow detection and sets the overflow bit of the status 
register as required. 
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Instruction Type 


SRL Shift 


SUB Arithmetic 


SUBB Arithmetic 


S U BI Arithm etic 


SUBK Arithmetic 


SUBXY Arithmetic 


TRAP N Program 


Control and 
Context 
Switching 


XO R Logical 


XORI Logical 


ZEXT Arithmetic 


Function 


Shifts the destination register field left by the value contained 
in a constant. The LSB of the destination register is always 
shifted to the carry bit of the status register. This instruction 
does not provide overflow detection. 


Subtracts the value in the source register from the destination 
register and stores the result in the destination register. 


Subtracts the value in the source register and carry bit of the 
status register from the destination register and stores the 
result in the destination register. 


Subtracts a 16 or 32-bit immediate value from the destination 
register and stores the result in the destination register. 


Subtracts a 5-bit constant value from the destination register 
and stores the result in the destination register. 


Individually subtract the X and Y halves of the source register 
from the X and Y halves of the destination register and stores 
the result in the destination register. 


Executes the software interrupt specified by N. Trap pushes 
PC and ST on the stack, then places the address pointed to 
by the track number. N is a number from 0 to 31 as shown 
below. 
N Trap Function 


0 Reset 
1 External Interrupt 1 
2 External Interrupt 2 
3-7 Traps 3 through 7 
8 Nonmaskable Interrupt 
9 Host Interrupt 
10 Display Interrupt 
11 Window violation 
12-29 Traps 12 through 29 
30 Illegal opcode 
31 Trap 31 


Performs a logical XOR of the contents of the destination 
register with the source register and stores the results in the 
destination register. 


Performs a logical XOR of the contents of the destination 
register with an immediate value and stores the results in the 
destination register. 


Zero extends the right justified field in the destination 
register. If the field size is not specified, the 34010 uses the 
default field size as a reference. 


As you can see from Tables 3-29 and 3-30, the 340xO provides a 
complex, but flexible, programming interface. This book cannot 
provide the detailed information required by the novice programmer 
to create programs for the 340xO. Refer to the Texas Instruments 
TMS340xO Software Development Kit for detailed programming 
information. However, you can use the tables in this book as a quick 
reference to the 340xO. In addition to the information provided by 
the tables, you need to know the addresses used by the display 
adapter for the host interface. Obtain this information from the 
manufacturer's technical manuals. 


Si(-Texas Instruments Graphics Architecture (TIGA) The 


Texas Instruments Graphics Architecture (TIGA) application 
interface allows you to program the TMS340xO using the simplified 
procedures provided in multiple assembly and C libraries. Table 3-31 
provides a summary of the TIGA instructions and their use. As with 
the processor instructions, this book does not provide the detailed 
instruction required by the novice programmer. Unlike the processor 
instructions, you must own a copy of the software development kit to 
use the TIGA interface. However, this book does provide a quick 
reference to the TIGA instruction set. In addition to the information 
provided by Table 3-31, you need to know the addresses used by the 
display adapter for the host interface. Obtain this information from 
the manufacturer's technical manuals. 


TIGA instruction set 
Table3-31 


Instruction 


Void BITBLT (Width, Height, 
SF]CX, SF}CY, DSTX, DSTY) 


lnt CD_ls_ALIVE ( ) 


Void 
CLEAF] FRAME BUFFEF3 
(Color) 


Type 


Pixel Array 
(Extended) 


Graphics System 
Initialization (Core) 


Clear (Core) 


Function 
Copies data from the source bitmap 
to the destination bitmap. Width and 
height describe the size of both 
bitmaps. SBCX and SBCY describe 
the starting coordinates of the source. 
DSTX and DSTY describe the starting 
coordinates of the destination. 
Returns 0 if the communication driver 
is not installed. Otherwise, returns a 
nonzero result. 
Clears the entire display memory by 
setting it to the specified color. Use 
the CLEAR SCREEN function to 
preserve off=creen data. 
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Instruction 


Void CLEAR_PAGE (Color) 


Void CLEAR SCF3EEN 
(Color) 


Void COP2GSP (COPID, 
COPADDR, GSPADDF3, 
Length) 


Short CPW (X, Y) 


Int CF]EATE ALM 
(RLM_Nama, ALM_Name) 


lnt CBEATE ESYM 
(GM_Namer 


lnt DELETE_FONT (lD) 


Void DF]AW_LINE (X1, Y1, 
X2, Y2) 


Void DF3AW_OVAL (W, H, 
XLeft, YTop) 


Type 


Clear (Core) 


Clear (Core) 


Communication 
(Core) 


Graphics Attribute 
Control (Core) 


Extensibility (Core) 


Extensibility (Core) 


Text (Extended) 


Graphics Output 
(Extended) 


Graphics Output 
(Extended) 


Function 


Clears the current drawing page by 
setting it to the specified color. Use 
the CLEAR SCREEN function to 
preserve off=creen data. 
Clears only the visible portion of 
display memory by setting it to the 
specified color. 


Copies data from the coprocessor 
address space to the TMS340 address 
space. Transfers occur in 32-bit 
length words. 


Outputs a 4-bit outcode based on a 
pixel's position within a window as 
shown here: 
Code Function 


0000 Point lies within window. 
01XX Point lies above window. 
10XX Point lies below window. 
XX01 Point lies left of window. 
XX10 Point lies right of window. 


Converts a relocatable load module to 
an absolute load module. Exits with a 
value of 0 if successful. 


Creates an external symbol table of 
global symbols. The linking loader uses 
this table to resolve references in a 
relocatable load module. Exits with a 
value of 0 if successful. 


Removes the font specified by ID 
(number) from the font table. Returns 
0 if the font was not installed. Returns 
nonzero value if font removed 
successfully. 


Draws a line onscreen. Xl and YI 
contain the starting coordinate. X2 
and Y2 contain the ending coordinate. 


Draws an oval onscreen. W contains 
the width. H contains the height. 
XLeft and YTop contain the 
coordinates of the upper-left corner 
of the oval. 


Instruction 


Void DRAW_OVALAF3C (W, 
H, XLeft, YTop, Theta, Arc) 


Void DRAW_PIEAF3C (W, H, 
XLeft, YTop, Theta, Arc) 


Void DF}AW_POINT (X, Y) 


Void DRAW_POLYLINE (N 
Points) 


Void DBAW_POLYLINE (N 
Points) 


Void DF}AW_F3ECT (W, H, 
XLeft, YTop) 


Unsigned Long 
FIELD_EXTF3ACT (GPTF3, FS) 


Void FIELD_lNSEBT (GPTB, 
FS, Data) 


Void FILL_CONVEX (N, 
Points) 


Type 


Graphics Output 
(Extended) 


Graphics Output 
(Extended) 


Graphics Output 
(Extended) 


Graphics Output 
(Extended) 


Poly Drawing 
(Extended) 


Graphics Output 
(Extended) 


Communication 
(Core) 


Communication 
(Core) 


Graphics Output 
(Extended) 


Function 


Draws an elliptical arc onscreen. W 
contains the width. H contains the 
height. XLeft and YTop contain the 
coordinates of the upper-left corner 
of the oval. Theta contains the start 
angle. Arc contains the number of 
degrees of arc. 


Draws an elliptical arc onscreen. Two 
lines emanate from the center of the 
arc to each end. W contains the width. 
H contains the height. XLeft and YTop 
contain the coordinates of the upper- 
left corner of the oval. Theta contains 
the start angle. Arc contains the 
number of degrees of arc. 


Draws a single pixel onscreen. X and 
Y contain the coordinate of the pixel. 


Draws a group of lines whose end 
points are supplied as a set of points. 
N indicates the number of lines to 
draw. Each point consists of an X and 
Y coordinate. To draw a closed 
polygon, use the same coordinates for 
the first and last set of points. 


See previous description. 


Draws a rectangle onscreen. W 
contains the width. H contains the 
height. XLeft and YTop contain the 
coordinates of the upper-left corner. 


Returns the 32-bit data in the 
TMS340 memory space pointed to 
by GPTB. FS contains the field size 
(number of significant bits). 


Writes Data to the address in 
TMS340 memory pointed to by 
GPTB. FS contains the field size. 


Draws a filled convex polygon. N 
indicates the number of vertices in the 
polygon. Each point consists of an X 
and Y coordinate. To draw a closed 
polygon, use the same coordinates for 
the first and last set of points. 


Table 3-31 Continued 


Instruction 


Void FILL_CONVEX (N 
Points) 


Void FILL_OVAL (W, H, 
XLeft, YTop) 


Void FILL_PIEAF3C (W, H, 
XLeft, YTop, Theta, Arc) 


Void FILL_POLYGON (N, 
Points) 


Void FILL_POLYGON (N, 
Points) 


Void FILL_POLYGON (N, 
Points) 


Void FILL_BECT (W, H, 
XLeft, YTop) 


lnt FLUSH_ESYM ( ) 


Void 
FLUSH_EXTENDED ( ) 


Void FF3AME_OVAL (W, H, 
XLeft, Ytop, DX, DY) 


Type 


Poly Drawing 
(Extended) 


Graphics Output 
(Extended) 


Graphics Output 
(Extended) 


Graphics Output 
(Extended) 


Poly Drawing 
(Extended) 


Workspace 
(Extended) 
Graphics Output 
(Extended) 


Extensibility (Core) 


Extensibility (Core) 


Graphics Output 
frtended) 


Function 


See previous description. 


Draws a filled oval onscreen. W 
contains the width. H contains the 
height. XLeft and YTop contain the 
coordinates of the upper-left corner 
of the oval. 


Draws a filled pie-shaped wedge 
onscreen. W contains the width. H 
contains the height. XLeft and.YTop 
contain the coordinates of the upper- 
left corner of the oval. Theta contains 
the start angle. Arc contains the 
number of degrees of arc. 


Draws a filled polygon. N indicates 
the number of vertices in the 
polygon. Each point consists of an X 
and Y coordinate. To draw a closed 
polygon, use the same coordinates for 
the first and last set of points. 


See previous description. 


See previous description. 


Draws a filled rectangle onscreen. W 
contains the width. H contains the 
height. XLeft and YTop contain the 
coordinates of the upper-left corner. 


Flushes an external symbol table of 
external symbols. The linking loader 
uses this table to resolve references in 
a relocatable load module. Exits with 
a value of 0 if successful. 


Flushes the TIGA extended functions 
and installed user functions. Then, 
removes the symbol table stored on 
the host. 


Fills the area between two concentric 
ovals with the current foreground color. 
W contains the width. H contains the 
height. XLeft and YTop contain the 


Instruction 


Void FF3AME_RECT (W, H, 
XLeft, Ytop, DX, DY) 


lnt 
FUNCTION IMPLEMENTED 
(Function C6de) 


Void GET COLOF]S 
(FColor,B-Color) 


Void GET_CONFIG (Con fig) 


Int GET_CURS_STATE ( ) 


Void GET_CUBS_XY (PX, PY) 


Void GET_ENV (Env) 


lnt GET_FONTINFO (lD, 
PFontlnfo) 


Type 


Graphics Output 
(Extended) 


Graphics System 
Initialization (Core) 


Graphics Attribute 
Control (Core) 


Graphics System 
Initialization (Core) 


Cursor (Core) 


Cursor (Core) 


Graphics Attribute 
Control (Core) 


Text (Core) 


Function 


coordinates of the upper-left corner of 
the oval. DX specifies the horizontal 
distance between the outer and inner 
ovals. DY specifies the vertical distance 
between the two ovals. 


Fills the area between two concentric 
rectangles with the current foreground 
color. W contains the width. H 
contains the height. XLeft and YTop 
contain the coordinates of the upper- 
left corner. DX specifies the horizontal 
distance between the outer and inner 
rectangles. DY specifies the vertical 
distance between the two rectangles. 


Queries if a board supports a specific 
function. Some TIGA implementations 
do not support the following functions: 


COP2GSP 
GET PALET 
GET-PALET ENTRY 
GSPZcOp 
INIT PALET 
SET-PALET 
SET-PALET ENTRY 
SET-TRANS-P 


Obtains the foreground and 
background color values. 


Obtains the current display adapter 
configuration and returns it in a 
structure. 


Returns 0 if the cursor is not enabled. 


Returns the coordinates of the cursor. 
Coordinates are relative to the upper- 
left corner of the visible screen. 


Returns the current graphics 
environment variable status in the 
structure pointed to by ENV. 


Returns information about the current 
font in a structure pointed to by 
PFontlnfo. ID determines which font 
the function polls. 0 returns system 
font information. -1 returns current 
font information. 
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Instruction 


Void GET ISP PBIOBITIES 
(NumlsF3sTPTfi) 


lnt GET MODEINFO 
(Index,-Modelnfo) 


Long 
GET NEAF3EST COLOF] 
(F3, G_, 8,I) 


Void 
GET OFFSCF{EEN MEM- 
ORY-(Num_BlocksT 
Off screen) 


Void GET_PALET (Palet Size, 
Palet) 


lnt GET PALET ENTF3Y 
(Index, fi, G, 8,-I) 


Long GET_PIXEL (X, Y) 


Long GET_PMASK ( ) 


Type 


Extensibility (Core) 


Graphics System 
Initialization (Core) 


Palette (Core) 


Pointer-Based 
Memory 
Management 
(Core) 


Palette (Core) 


Palette (Core) 


Graphics Utility 
(Extended) 


Graphics Attribute 
Control (Core) 


Function 


Returns the priorities of interrupt 
service routines installed using the 
INSTALL RLM and INSTALL ALM 
functions.-NumlsBscontainsFhe 
number of ISRs installed. PTP points 
to an array of short containing the 
priority data. 
Returns a structure containing the 
board configuration supported by the 
current board and monitor. Index 
contains the mode number. 


Obtains the color number that most 
closely matches the specified 
parameters. B is red, G is green, 8 is 
blue, and I is intensity. 


Returns a description of the offscreen 
memory areas that are not in use. 
These blocks normally consist of 
display memory that is not used for 
the frame buffer or alternate frame 
buffer. You obtain the Num Blocks 
parameter using the GET_C-ONFIG 
function. Off screen is a pointer to 
memory allocated for offscreen entry 
storage. 


Reads an entire palette register into 
the palette array. You obtain the 
Palet Size parameter using the 
GET CONFIG function. 


Reads the color values contained in a 
single palette. I ndex specifies which 
palette to read. 8 is red, G is green, 
8 is blue, and I is intensity. This 
function returns 0 if you specify an 
invalid index. 


Returns the value of the pixel at the 
address specified by X and Y. The 
coordinate is relative to the drawing 
Origin. 


Returns the value of the plane mask 
(planes enabled/disabled for writing). 


Instruction 


lnt GET_PPOP ( ) 


lnt GET_TEXTATTR (Pcontrol, 
Count, Arg) 


Int GET_TRANSP ( ) 


Unsigned Long 
GET_VECTOF} (TrapNum) 


lnt GET_VIDEOMODE ( ) 


Int GET_WINDOWING ( ) 


Type 


Graphics Attribute 
Control (Core) 


Text (Extended) 


Graphics Attribute 
Control (Core) 


Communication 
(Core) 


Graphics System 
Initialization (Core) 


Graphics Attribute 
Control (Core) 


Function 


Returns a 5-bit code for the current 
pixel processing operation. 
Code Function 


0 Source 
1 Source AND Destination 
2 Source AND NOT Destination 
3 All os 
4 Source oR NOT Destination 
5 Source EQU Destination 
6 NOT Destination 
7 Source NOR Destination 
8 Source oR Destination 
9 Destination 


10 Source XOR Destination 
11 NOT Source AND Destination 
12 All ls 
13 NOT Source oR Destination 
14 Source NAND Destination 
15 NOT Source 
16 Source + Destination 
17 ADDS (Source, Destination) 
18 Destination -Source 
19 SUBS (Destination, Source) 
20 MAX (Source, Destination) 
21 MIN (Source, Destination) 


Obtains the text rendering attributes. 
Pcontrol is a pointer to a list of 
desired attributes. Current attribute 
values include °/oa (top left alignment 
= 0, baseline = 1) and °/oe (additional 
intercharacter spacing). Cou nt 
contains the number of attributes in 
the control string. 


Gets the state of the transparency (T) 
bit of the control register. Returns 0 if 
transparency is disabled. 


Obtains the address of the trap 
vector specified by TrapNum. 


Returns the current video mode 
emulation number. 


Gets the 2-bit windowing code in the 
control I/0 register as shown here: 
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Instruction 


Short GET_WKSP (Addr, 
Pitch) 


Long GSP_CALLOC 
(NMemB, Size) 


Void GSP_EXECUTE (Entry 
Point) 


Int GSP_FREE (PTF]) 


Type 


Workspace (Core) 


Pointer-Based 
Memory 
Management 
(Core) 


Graphics System 
Initialization (Core) 


Pointer-Based 
Memory 
Management 
(Core) 


Long GSP_MALLOC (Size) Pointer-Based 


Memory 
Management 
(Core) 


Long GSP_MAXHEAP ( ) 
Pointer-Based 
Memory 
Management 
(Core) 


Void GSP_MINIT (Stack size) Pointer-Based 


Memory 
Management 
(Core) 


Long GSP_REALLOC (PTF}, Pointer-Based 


Function 
Code Function 


00 Nowindowing 
01 Interrupt Request on write In 


Window 


10 Interrupt Request on write 


Outside Window 


11 Clip to window 


Returns parameters defining the 
current off screen workspace. If the 
function returns a nonzero value, then 
Addr and Pitch contain the address 
and pitch of the workspace area. 


Allocates enough TMS340 memory 
to contain NMemB objects of Size. 
Returns 0 if not enough memory 
remains. Otherwise, returns a pointer 
to the memory area. 


Loads and executes a non-application 
function. In other words, this function 
provides a portable COFF loader. 
Deallocates the memory allocated by 
the GSP_MALLOC, GSP_CALLOC, 
or GSP REALLOC functions. PTF3 
points t6 the beginning of the 
memory area. Returns 0 if not 
successful. 


Allocates the amount of TMS340 
memory specified by Size. Returns 0 
if not enough memory remains. 
Otherwise, returns a pointer to the 
memory area. 


Returns the largest amount of heap 
available for allocation. 


Deallocates all dynamically allocated 
memory in the TMS340 heap. Also 
changes the size of the stack. 
Providing a value of -1 allocates the 
default stack size. 


Changes the size of the previously 


Instruction 


Size) 


Void GSP2COP (COPID, 
GSPAddr, COPAddr, 
Length) 


Void GSP2GSP (Addrl , 
Addr2, Length) 


Void GSP2HOST (GPTR, 
HPTR, Length, Swizzle) 


Void GSP2HOSTXY (SAddr, 
SPTCH, DAddr, DPTCH, 
SX, SY, DX, DY, XExt, YExt, 
Psize, Swizzle) 


Void HOST2GSP (GPTR, 
HPTF3, Length, Swizzle) 


Void HOST2GSPXY (SAddr, 
SPTCH, DAddr, DPTCH, 
SX, SY, DX, DY, XExt, YExt, 
Psize, Swizzle) 


Type 


Memory 
Management 
(Core) 


Communication 
(Core) 


Pointer-Based 
Memory 
Management 
(Core) 


Communication 
(Core) 


Communication 
(Core) 


Communication 
(Core) 


Communication 
(Core) 


Function 


allocated memory block pointed to by 
PTB. Size determines the new size of 
memory allocation. Returns 0 if not 
successful. 


A TMS34020 and above specific 
function that copies data from the 
TMS340 address space to the 
coprocessor address space. 


Copies data within the TMS340 
address area. Addrl contains the 
source address, Addr2 contains the 
destination address, and Length 
contains the length of the data. 


Transfers data from TMS340 
memory (GPTB) to host memory 
(HPTB). Length contains the length 
of data to transfer. If Swizzle is 
nonzero, the 34010 reverses the 
order of the bits in each byte before 
transfer. 


Transfers a rectangular area of the 
TMS340 bitmap to the host. SAddr 
contains the source address; DAddr 
contains the destination address. The 
source area starts at SX, SY and is 
transferred to DX, DY. XExt and YExt 
define the size of the area to transfer. 
Psize contains the size of the pixels 
transferred. SPTCH and DPTCH 
contain the source and destination 
pitch. If Swizzle is nonzero, the 
34010 reverses the order of the bits 
in each byte before transfer. 


Transfers data from host memory 
(HPTB) to TMS340 memory (GPTB). 
Length contains the length of data to 
transfer. If Swizzle is nonzero, the 
34010 reverses the order of the bits 
in each byte before transfer. 


Transfers a rectangular area of host 
memory to the TMS340. SAddr 
contains the source address; DAddr 
contains the destination address. The 
source area starts at SX, SY and 
transfers to DX, DY. XExt and YExt 
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Instruction 


Void lNIT_PALET ( ) 


Void lNIT_TEXT ( ) 


lnt INSTALL_ALM (ALM 
Name) 


Type 


Palette (Core) 


Text (Core) 


Extensibiliky (Core) 


Short INSTALL_FONT (PFont) Text (Extended) 


lnt INSTALL_PF]lMITIVES ( ) Graphics system 


Initialization (Core) 


lnt INSTALL_PBIMITIVES ( ) 


lnt INSTALL_RLM (F3LM 
Name) 


Void INSTALL USEF3ERROF3 
(Function Narie) 


Int LMO (N) 


Extensibility (Core) 


Extensibility (Core) 


Graphics System 
Initialization (Core) 


Graphics Utility 
(Core) 


Function 


define the area to transfer. Psize 
contains the size of the pixels. SPTCH 
and DPTCH contain source and 
destination pitch. If Swizzle is 
nonzero, the 34010 reverses the 
order of the bits in each dyte before 
transfer. 


Initializes the first 16 palette entries to 
the EGA default palette. 


Removes any installed fonts from 
memory and selects the standard font. 
Resets all text drawing attributes. 


Installs the absolute load module into 
the TIGA graphics manager and 
returns a module identifier. Use the 
module identifier to invoke the ALM 
extended functions. Returns a 
negative number if not successful. 


Use this function to install a font into 
the font table after loading it into 
TMS340 memory. PFont points to 
the location of the font file in 
memory. The function returns an ID 
number when successful. Otherwise, 
it returns 0. 


Loads extended graphics primitives in 
memory. Returns a positive number 
identifier when successful. Returns a 
negative number error otherwise. 


See previous description. 


Installs a relocatable load module into 
the TIGA graphics manager and 
returns a module identifier. Use the 
module identifier to invoke the RLM 
extended functions. Returns a 
negative number if not successful. 


Substitutes the default host 
communication error messages with a 
user supplied error handling routine. 


Calculates the position of the leftmost 
1 in N. This function treats N as a 
32-bit number. Returns -1 if no one 


Instruction 
Type 


Unsigned Long LOADCOFF 
(Filename) 


Short PAGE_BUSY ( ) 


Int PAGE_FLIP (Display, 
Drawing) 


Void PATNFILL_CONVEX (N 
Points) 


Void PATNFILL_CONVEX(N, 
Points) 


Void PATNFILL_OVAL (W, H, 
XLeft, YTop) 


Void PATNFILL_PIEARC (W, 
H, XLeft, YTop, Theta, Arc) 


Void PATNFILL POILYGON 
(N, Points) 


Graphics System 
Initialization (Core) 


Graphics Utility 
(Core) 


Graphics Utility 
(Core) 


Graphics Output 
(Extended) 


Poly Drawing 
(Extended) 


Graphics Output 
(Extended) 


Graphics Output 
(Extended) 


Graphics Output 
(Extended) 


Function 


found. Otherwise, returns the bit 
position of the one. 


Provides the capability to load 
portable COFF code into the graphics 
manager. Not generally used by 
application programs. 


Used with the PAGE FLIP function. 
Returns a nonzero n=mber while 
page flipping in progress. Otherwise, 
it returns 0. 


Used with multiple frame buffers to 
set the display page to a particular 
frame buffer and the drawing page 
for subsequent drawing operations. 


Fills a convex polygon with a 
pattern. N defines the number of 
vertices in the polygon. Points is an 
array containing the coordinates of 
each of the vertices in the polygon. 
The first and last X,Y coordinate in 
Points should be the same to make 
sure the polygon is closed. Uses the 
currently defined pattern for fill. 


See previous description. 


Draws a pattern-filled oval onscreen. 
W contains the width. H contains the 
height. XLeft and YTop contain the 
coordinates of the upper-left corner 
of the oval. Uses the currently defined 
pattern for fill. 
Draws a pattern-filled pie-shaped 
wedge onscreen. W contains the 
width. H contains the height. XLeft 
and YTop contain the coordinates of 
the upper-left corner of the oval. 
Theta contains the start angle. Arc 
contains the number of degrees of 
arc. Uses the currently defined 
pattern for fill. 
Draws a pattern-filled polygon. N 
indicates the number of vertices in the 
polygon. Each point consists of an X 
and Y coordinate. To draw a closed 
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Instruction 


Void PATNFILL POLYGON 
(N, Points) 


Void PATNFILL POLYGON 
(N, Points) 


Void PATNFILL_RECT (W, H, 
XLeft, YTop) 


Void PATNFRAME_OVAL (W, 
H, XLeft, Ytop, DX, DY) 


Void PATNFBAME_BECT (W, 
H, XLeft, YTop, DX, DY) 


Type 


Poly Drawing 
(Extended) 


Workspace 
(Extended) 


Graphics Output 
(Extended) 


Graphics Output 
(Extended) 


Graphics Output 
(Extended) 


Void PATNPEN_LINE (X1, Yl, Graphics output 
X2, Y2) 


Void PATNPEN OVALAF3C 
(W, H, XLeft, YFop, Theta, 
Arc) 


(Extended) 


Graphics Output 
(Extended) 


Function 


polygon, use the same coordinates for 
the first and last set of points. Uses 
the currently defined pattern for fill. 


See previous description. 


See previous description. 


Draws a pattern-filled rectangle 
onscreen. W contains the width. H 
contains the height. XLeft and YTop 
contain the coordinates of the upper- 
left corner. Uses the currently defined 
pattern for fill. 
Pattern fills the area between two 
concentric ovals. W contains the 
width. H contains the height. XLeft 
and YTop contain the coordinates of 
the upper left corner of the oval. DX 
specifies the horizontal distance 
between the outer and inner ovals. 
DY specifies the vertical distance 
between the two ovals. Uses the 
currently defined pattern for fill. 


Pattern fills the area between two 
concentric rectangles. W contains the 
width. H contains the height. XLeft 
and YTop contain the coordinates of 
the upper-left corner. DX specifies the 
horizontal distance between the outer 
and inner rectangles. DY specifies the 
vertical distance between the two 
rectangles. Uses the currently defined 
pattern for fill. 
Draws a patterned line onscreen. Xl 
and Yl contain the starting 
coordinate. X2 and Y2 contain the 
ending coordinate. Uses the currently 
defined pattern for drawing. Use the 
SET_PENSIZE function to change 
pen width and height. 
Draws a patterned elliptical arc 
onscreen. W contains the width. H 
contains the height. XLeft and YTop 


Instruction 


Void PATNPEN_PIEAF3C (W, 
H, XLeft, YTop, Theta, Arc) 


Void PATNPEN_POINT (X, Y) 


Void PATNPEN POLYLINE 
(N, Points) 


Void PATNPEN POLYLINE 
(N, Points) 


Long PEEK_BF3EG (BF3EG) 


Type 


Graphics Output 
(Extended) 


Graphics Output 
(Extended) 


Graphics Output 
(Extended) 


Poly Drawing 
(Extended) 


Graphics Utility 
(Core) 


Void PEN_LINE (Xl , Y1, X2, Graphics output 


Function 


contain the coordinates of the upper- 
left corner. Theta contains the start 
angle. Arc contains the degrees of 
arc. Uses the currently defined 
pattern for drawing. Use the 
SET_PENSIZE function to change 
pen width and height. 
Draws a patterned elliptical arc 
onscreen. Two lines emanate from 
the center of the arc to each end. W 
contains the width. H contains the 
height. XLeft and YTop contain the 
coordinates of the upper-left corner. 
Theta contains the start angle. Arc 
contains the degrees of arc. Uses the 
currently defined pattern for drawing. 
Use the SET PENSIZE function to 
change pen viidth and height. 


Draws rectangular set of pixels 
onscreen (corresponds to pen height 
and width). The pixel color depends 
on its position within the currently 
defined pattern. X and Y contain the 
coordinate of the pixel. Use the 
SET_PENSIZE function to change 
pen width and height. 
Draws a group of patterned lines 
whose end points are supplied as a 
set of points. N indicates the number 
of lines to draw. Each point consists 
of an X and Y coordinate. To draw a 
closed polygon, use the same 
coordinates for the first and last set of 
points. Uses the currently defined 
pattern for drawing. Use the 
SET_PENSIZE function to change 
pen width and height. 
See previous description. 


Returns a 32-bit number containing 
the value of a B-file register. BBEG 
contains a number from 0 to 15 
corresponding to a file register 
number. 


Draws a line the width and height of 
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Instruction 


Y2) 


Void PEN_OVALAF{C (W, H, 
XLeft, YTop, Theta, Arc) 


Void PEN_PIEABC (W, H, 
XLeft, YTop, Theta, Arc) 


Void PEN_POINT (X, Y) 


PEN_POLYLINE (N, Points) 


PEN_POLYLINE (N, Points) 


Void POKE_BBEG (BBEG, 
Value) 


Type 


(Extended) 


Graphics Output 
(Extended) 


Graphics Output 
(Extended) 


Graphics Output 
(Extended) 


Graphics Output 
(Extended) 


Poly Drawing 
(Extended) 


Graphics Utility 
(Core) 


Function 


of the current pen onscreen. Xl and 
Yl contain the starting coordinate. X2 
and' Y2 contain the ending coordinate. 
Use the SET PENSIZE function to 
change pen dridth and height. 
Draws an arc the width and height of 
the current pen onscreen. W contains 
the width. H contains the height. 
XLeft and YTop contain the 
coordinates of the upper-left corner. 
Theta contains the start angle. Arc 
contains the degrees of arc. Use the 
SET_PENSIZE function to change 
pen width and height. 
Draws an arc the width and height of 
the current pen onscreen. Two lines 
emanate from the center of the arc to 
each end. W contains the width. H 
contains the height. XLeft and YTop 
contain the coordinates of the upper- 
left corner. Theta contains the start 
angle. Arc contains the degrees of 
arc. Use the SET PENSIZE function 
to change pen width and height. 
Draws a rectangular set of pixels 
onscreen (corresponds to pen height 
and width). X and Y contain the 
coordinate of the pixel. Use the 
SET_PENSIZE function to change 
pen width and height. 
Draws a group of lines the width and 
height of the current pen whose end 
points are supplied as a set of points. 
N indicates the number of lines to 
draw. Each point consists of an X and 
Y coordinate. To draw a closed 
polygon, use the same coordinates for 
the first and last set of points. Use the 
SET_PENSIZE function to change 
pen width and height. 
See previous description. 


Writes Value to the B-file register 
specified by BBEG. Value is a 32-bit 
number. 


Instruction 


lnt BMO (N) 


lnt SEED_FILL (Xseed, 
Yseed, Buffer, Maxbytes) 


lnt SEED_PATNFILL (Xseed, 
Yseed, Buffer, Maxbytes) 


lnt SELECT_FONT (ID) 


Void SET_BCOLOF} (Color) 


Void SET_CLIP_RECT (W, H, 
XLeft, YTop) 


Void SET_COLOF3S (FColor, 
BColor) 


lnt SET_CONFIG (Graphics 
Mode, lnit Draw) 


Type 


Graphics Utilfty 
(Core) 


Graphics Output 
(Extended) 


Graphics Output 
(Extended) 


Text (Extended) 


Graphics Attribute 
Control (Core) 


Graphics Attribute 
Control (Core) 


Graphics Attribute 
Control (Core) 


Graphics System 
Initialization (Core) 


Function 


Calculates the position of the rightmost 
1 in N. This function treats N as a 
32-bit number. Returns -1 if no one 
found. Otherwise, returns the bit 
position of the one. 


Fills a region of connected pixels 
starting a specified seed pixel. Xseed 
and Yseed contain the coordinates of 
the seed pixel. Buffer is an area of 
memory set aside for working 
storage. Maxbytes is the number of 
8-bit bytes in the storage area. 


Pattern fills a region of connected 
pixels starting a specified seed pixel. 
Xseed and Yseed contain the 
coordinates of the seed pixel. Buffer 
is an area of memory set aside for 
working storage. Maxbytes is the 
number of 8-bit bytes in the storage 
area. Uses the currently defined 
pattern for fill. 


Selects a previously installed font for 
use. ID is the number returned after 
font installation. 


Changes the background color 
specified in the COLOR0 B-file 
register to Color. 


Sets the current clipping rectangle by 
updating the B-file registers WSTART 
and WEND to match the W and H 
parameters. XLeft and YTop are 
relative to the drawing origin. 


Changes the foreground color 
specified in the COLORI B-file 
register to FColor. Also changes the 
background color specified in the 
COLOR0 B-file register to BColor. 


The SET_CONFIG function changes 
the mode to match Graphics Mode. 
If the mode is invalid, returns 0. 
Otherwise, returns a nonzero result. 
Init Draw causes the function to reset 
the following parameters when set 
true (nonzero). 
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Instruction 


Void SET CUF3S SHAPE 
(Shape) 


Void SET CUF3S STATE 
(Enable) 


Void SET_CURS_XY (X, Y) 


Void SET DRAW ORIGIN 


(X, Y) 
Void SET_DSTBM (Addr, 
Pitch, XExt, YExt, Psize) 


Type 


Cursor (Core) 


Cursor (Core) 


Cursor (Core) 


Graphics Attribute 
Control (Extended) 


Pixel Array 
(Extended) 


Function 


Transparency is disabled 
(CONTROL I/0 Register). 


Window Clipping is set 
(CONTROL I/0 Register). 
Pixel Processing is set to replace 
(CONTROL I/0 Register). 
PMASK I/0 Register is set to 0. 


Foreground color is set to light 
gray and background color to black. 
Source and destination bitmaps 
are set to the screen. 


Drawing origin is set to 0, 0. 


Pen width and height are set to 1. 


Current pattern address is set to 0. 


All installed fonts are removed 
and the current selected font set to 
the system font. 


Graphics cursor placed in the 
center of the screen, turned off, and 
set to the default shape. 


Temporary workspace is 
initialized. 


Defines the size and shape of the 
cursor. Shape is a structure 
containing size, color, and shape 
bitmaps. 


Displays the cursor if Enable is 
nonzero. Removes cursor if Enable 
is zero. 


Sets the pixel coordinates of the 
cursor hotspot. The cursor 
coordinates are relative to the upper- 
left corner of the screen. 


Sets the drawing origin for future 
drawing operations. 


Sets the destination bitmap for future 
BITBLT operations. An address value 
of 0 sets the destination to screen. 


Instruction 


Void SET_FCOLOF} (Color) 


Void SET INTEF3RUPT 
(Level, Priority, Enable, 
Scan Line) 


Void SET_PALET (Count, 
Index, Palet) 


Void SET PALET ENTF3Y 
(Index, F3TG, 8, IT 


Void SET_PATN (P) 


Void SET_PENSIZE (W, H) 


Void SET_PMASK (Mask) 


Void SET_PPOP (PPOP 
Code) 


Type 


Graphics Attribute 
Control (Core) 


Extensibility (Core) 


Palette (Core) 


Palette (Core) 


Graphics Attribute 
Control (Extended) 


Graphics Attribute 
Control (Extended) 


Graphics Attribute 
Control (Core) 


Graphics Attribute 
Control (Core) 


Function 


Changes the foreground color 
specified in the COLORI B-file 
register to Color. 


Enables or disables a previously 
installed interrupt service routine. The 
Scan Line parameter is used for 
display interrupts only. It sets the scan 
line at which the interrupt becomes 
enabled. 


Loads an entire palette into memory. 
Count contains the number of palette 
entries. Index contains the palette 
loading start point. Palet contains 
groups of four values (R, G, 8, and I). 
Each group defines one palette value. 


Loads a single palette into memory. 
Index contains the palette entry to 
replace. 8, G, 8, and I contain the 
color values for the palette entry. 


Defines the pattern used for drawing 
operations. P is a pointer to a 
structure containing the height, width, 
depth, and bit pattern. 


Sets the width (W) and height (H) of 
the drawing pen. 


Defines which plane mask bits are 
writable. A zero in a bit position 
enables writing. A one in a bit 
position disables writing. 
Defines the pixel processing 
for future drawing operations. 
Code Function 


0 Source 
1 Source AND Destination 
2 Source AND NOT Destination 
3 All os 
4 Source oR NOT Destination 
5 Source EQU Destination 
6 NOT Destination 
7 Source NOR Destination 
8 Source oR Destination 
9 Destination 


10 Source XOR Destination 
11 NOT Source AND Destination 
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Instruction 


Void SET_SBCBM (Addr, 
Pitch, XExt, YExt, Psize) 


lnt SET_TEXTATTF3 (Pcontrol, 
Count, Arg) 


Void SET_TIMEOUT (Value) 


Void SET_TRANSP (Mode) 


Unsigned SET_VECTOR 
(TrapNum, NewAddr) 


lnt SET_VIDEOMODE (Mode, 
Style) 


Type 


Pixel Array 
(Extended) 


Text (Extended) 


Graphics System 
Initialization (Core) 


Graphics Attribute 
Control (Core) 


Communication 
(Core) 


Graphics System 
Initialization (Core) 


Function 


Code Function 


12 All ls 
13 NOT Source oR Destination 
14 Source NAND Destination 
15 NOT Source 
16 Source + Destination 
17 ADDS (Source, Destination) 
18 Destination -Source 
19 SUBS (Destination, Source) 
20 MAX (Source, Destination) 
21 MIN (Source, Destination) 


Sets the source bitmap for future 
BITBIJT operations. An address value 
of 0 sets the source to screen. 
Sets the text rendering attributes. 
Pcontrol is a pointer to a list of 
desired attributes. Current attribute 
values include 0/oa (top left alignment 
= 0, baseline = 1) and °/oe (additional 
intercharacter spacing). Count 
contains the number of attributes in 
the control string. 
Sets the time in milliseconds that the 
host waits for a TMS340 function to 
complete before calling the error 
function. 
Changes the transparency mode 
(TMS34020 and above only) as shown 
here (TMS34010 uses mode 2 only): 
Mode Function 


Source transparency = 0 
Source transparency = 
COLOR0 
Result transparency = 0 
Result transpareney = 
COLORO 


Sets the specified trap number to 
NewAddr. Returns the address of the 
old interrupt. 
The SET VIDEOMODE function 
changes t-he current video mode and 
determines how to initialize the new 
mode. Mode can contain one of the 
following values: TIGA, MDA, 


Instruction 


Void SET_WINDOWING 
(Enable) 


Type 


Graphics Attribute 
Control (Core) 


Void SET_WKSP (Addr, Pitch) Workspace (Core) 


Void STYLED_LINE (Xl , Y1, 
X2, Y2, Style, Mode) 


Void SWAP_BM ( ) 


Graphics Output 
(Extended) 


Pixel Array 
(Extended) 


Function 


HERCULES, CGA, EGA, VGA, 
AI_8514, or PREVIOUS. Style 
determines the initialization method. 
It can contain one of the following 
values: NO_INIT, INIT_GLOBALS, 
INIT, or CLR_SCREEN. 


Sets the 2-bit windowing code in the 
control I/0 register as shown here: 
Code Function 


00 No windowing 
01 Interrupt Request on write In 


Window 


10 Interrupt Request on write 


Outside Window 


11 Clip to window 


Sets parameters defining the current 
offscreen workspace. Addr and Pitch 
contain the address and pitch of the 
workspace area. 


Uses Bresenham's algorithm to 
draw a styled line from Xl , Yl to X2, 
Y2. Style is a 32-bit value containing 
a repeating pattern. Mode changes 
the method used for drawing: 
Mode Function 


0 Do not draw background 


pixels, leave gaps. Load new 
line-style from style argument. 


1 Draw background pixels using 


COLORO. Load new line- 
style from style argument. 


2 Do not draw background 


pixels, leave gaps. Do not 
load new line-style from style 
argument. 


3 Draw background pixels 


using COLORO. Do not load 
new line-style from style 
argument. 


Exchanges pointers to the structures 
containing the source and destination 
bitmaps. 
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Instruction 


Void SYNCHRONIZE ( ) 


lnt TEXT_OUT (X, Y, Pstring) 


lnt TEXT_WIDTH (Pstring) 


Void TBANSP_OFF ( ) 


Void TRANSP_ON ( ) 


Void WAIT_SCAN (Line) 


Void ZOOM_F3ECT (WS, HS, 
XS, YS, WD, HD, XD, YD, 
LineBuf) 


Type 


Graphics System 
Initialization (Core) 


Text (Core) 


Text (Extended) 


Graphics Attribute 
Control (Core) 
Graphics Attribute 
Control (Core) 
Graphics Utility 
(Core) 


Pixel Array 
(Extended) 


Function 


Synchronizes operations between two 
processors. Ensures the TMS340 
completes an operation before the 
host CPU tries to manipulate the 
resulting data. 
Sends an ASCII string pointed to by 
Pstring to the display using the 
current font. X and Y specify the 
starting coordinates for the string. 
Returns the length of the specified 
string in pixels (using the current font 
for reference). 
Disables transparency for future 
drawing operations. 
Enables transparency for future 
drawing operations. 
Causes a wait state until the processor 
scans the specified scan line. Control 
returns to the calling procedure. 
Synchronizes drawing operations with 
the display. 
Expands or shrinks the specified 
rectangle to fit on the display. WS 
contains the source width. HS 
contains the source height. XS and 
YS contain the coordinates of the 
upper-left corner of the source 
screen. WD contains the destination 
width. HD contains the destination 
height. XD and YD contain the 
coordinates of the upper-left corner 
of the destination screen. LineBuf is a 
buffer large enough to contain one 
line of the display. 


As shown by Table 3-31, the TIGA instruction set falls into 14 main 
categories. In addition, each instruction also falls into one of two 
types. TIGA instruction types include core and extended. Core 
instructions are always available. They remain constant over the 
entire range of TIGA compatible boards. You must load an extended 
function into the TIGA environment before using it. This allows you 
to substitute one instruction for another. Always consult the 
manufacturer documentation before using an extended function. 


There are 14 TIGA instruction categories. The graphics system 
initialization functions allow you to determine the presence of a TIGA 
compatible board and place the 340xx in a predefined state. There 
are different methods of performing this task. Each instruction 
performs the task of initialization in a different way. The clear 
functions allow you to clear all or part of display memory. The 
graphics attribute control functions allow you to change how the 
graphics processor executes various instructions. These attributes 
include foreground color, background color, plane mask, pixel 
processing, transparency, windowing, drawing origin, fill pattern, and 
drawing pen. The palette function allows you to change the final 
color used to paint the display on screen. These functions vary in 
scope from manufacturer to manufacturer. The graphics output 
function performs the actual drawing of objects in display memory. 
The poly drawing function provides extended graphics drawing 
functions. The workspace functions provide a method of temporarily 
allocating memory to manipulate a graphics object. The pixel array 
functions allow you to define pixel blocks and move them within 
display memory. The text functions provide the means to send text to 
the display. These functions depend on the availability of TIGA font 
files. You must install a font before using these functions. The cursor 
functions change the appearance and position of the cursor on- 
screen. The graphics utility functions consist of miscellaneous 
housekeeping instructions. The pointer-based memory-management 
functions allow you to allocate and deallocate dynamic memory. In 
addition, these functions provide statistics on memory status. The 
communication functions determine how and when the display 
adapter communicates with the host. Finally, the extensibility 
functions allow you to add or delete functions from the TIGA 
environment. 


As you can see, each category of TIGA instruction performs a 
specific task in relation to the graphics environment. Using this 
interface not only allows you to create portable code, but also to 
develop programs quickly and easily. 


-*- Extended Graphics Array (XGA) The XGA is one of the 


newest display adapters on the market. It provides higher resolution 
and more colors than the 8514/A display adapter. The XGA also 
outperforms most SVGA display adapters. The best part is that the 


XGA delivers this performance at a lower cost than buying a 
processor-driven display adapter like those designed around the 
TMS340xO chip. IBM originally designed this adapter for the PS/2, 
but several vendors have made a commitment to produce it for other 
platforms as well. 


Figure 3-3 shows a typical XGA implementation. Most vendors 
deviate from this design, but the one here tells you a lot about this 
design of this adapter. Notice that it does not follow the VGA or 
TMS34010 designs at all. It provides many new function blocks 
including the sprite and attribute controls. In addition, the 
coprocessor controls all advanced functions on this display adapter. 
There are some similarities. For example, all three adapters use a 
DAC to convert their digital signals to analog output. 


XGA Block diagram. 


The XGA does provide full VGA register level compatibility, so you 
can use the registers described in the previous section with this 
adapter. It also provides many other display features that are not 
documented as part of the VGA register set. VESA hopes to avoid 


-::-:---I------:i:_----:: 


the proliferation of interface techniques that plagued the VGA and 
the SVGA adapter by producing an XGA standard for these 
additional capabilities early. This standard is VXE 1.0. The following 
paragraphs outline the register level aspect of this standard. This 
book pursues the VESA standard rather than looking at the IBM XGA 
directly to ensure that applications you create will run on the widest 
range of available hardware. 


Note.. The VESA standard does refer to the IBM documentation 
contained in the ``Update for the Personal System/2 Hardware 
Interface Technical Reference Common Interfaces" part number 
04G3281 (form number S04G-3281-00). 


The XGA uses a different mechanism than other display adapters f or 
positioning itself in system memory and I/0 address space. Rather 
than use fixed addresses like the VGA or device driver addresses like 
the TMS34010, the XGA uses a POS setup to determine its location 
in memory. Each vendor receives a POS identification for their card 
from either IBM or VESA. The list of POS IDs include: 8FD8h, 
8FD9h, 8FDAh, and 8FDBh. The way that the vendor implements 
the POS id.entification code varies by system as follows: 


> MCA machines-You must place each board to setup mode and 


query it. Use the IBM-prescribed interrupt 15h service C4h 
BIOS call to check all the expansion boards. Write ODh to port 
94h to set the onboard system video to setup mode, then write 
OFFh to port 94h to enable it. 


> ISA machines-Directly access the POS registers using the I/0 


address range from 108h to 10Fh. Make sure you follow any 
vendor specific addressing schemes for this method. 


> EISA Machines-Read the POS data directly from slot 


addresses zC88h through zCBFh. You also can use the EISA 
setup to enable the POS registers. 


Once you locate an XGA in the system, you must determine several 
addresses from the remainder of the POS bytes including: ROM 
address, XGA instance, and video memory address. Simply add the 
required offset to the base address and read the port. Never write to 
these ports. 


The first two offsets (base address + 0 and base address + 1) contain 
the low and high bytes of the subsystem identification register, 
respectively. You use this identification number to see if the board 
installed in the current slot is an XGA. 


The POS register (base address + 2) contains four pieces of 
information. Bit 0 is the subsystem enable. Bits 1 through 3 are the 
XGA instance number. Cross reference this instance number to an 
I/0 base address using the following equation: I/0 Address = 2100h 
+ (10 x Instance Number). For example, if you wanted to look at 
XGA instance 1, the base I/0 address is 2110h. Bits 4 through 7 
contain the ROM address. The ROM address space is 8K. The first 
7K of this range is occupied by the ROM; the remaining lK is 
occupied by the coprocessor memory mapped registers. To convert 
the ROM address number to an address use the following equation: 
C0000h + (2000h x ROM Address Number). For example, if you 
were looking for the second instance of ROM address 3, then the 
ROM address would equal C6000. Once you calculate the ROM 
address, you can use this information to find the coprocessor register 
base address using the following equation: ROM Address + 1C00h + 
(80h x XGA Instance Number). 


Offset base address + 4 contains two pieces of information. Bit 0 
contains the video memory enable flag. Bits 1 through 7 contain the 
seven most significant bits of the video memory base address. This is 
a 32-bit number where bits 0 through 21 are the location in video 
memory that you want to look at (set to zero to get the base address), 
bits 22 through 24 are the instance number (from bits 1 through 3 of 
the register at base address + 2), and bits 25 through 31 are the most 
significant bits from the current register (bits 1 through 7 of base 
address + 4). 


The sixth offset (base address + 5) contains the lMB aperture base 
address. If this register contains 0, then the aperture is disabled. 
Otherwise, you can find the base address by multiplying the base 
address number by 100000h. 


The XGA also provides direct access to a number of internal 
registers. (Remember, these registers are in addition to the VGA 
registers described in the previous section.) Table 3-32 contains a 


complete list of the registers you can access directly. The x in the 
address represents the instance number of the adapter. For example, 
if you wanted to access the Memory Access Mode register for the 
second XGA instance, you would use I/0 address 2129h. 


XGA registerset 
Table 3-32 


I/0 Address 


21xO 
21xl 
21x2-21x3 
21x4 
21x5 
21x6 
21x7 
21x8 
21x9 
21xA 
21xB-21xF 


Description 


Operating Mode 
Aperture Control 
Reserved 
Interrupt Enable 
Interrupt Status 
Virfual Memory Control 
Virtual Memory Interrupt Status 
Aperture Index 
Memory Access Mode 
Index 
Data 


Each of the direct access registers allows you to perform specific 
tasks with the extended modes of the XGA. Tables 3-33 through 3- 
40 contain detailed information about these registers. The registers 
allow you full read and write capability. In addition, you can assume 
all the registers provide 8-bit access unless otherwise specified. 


Operating mode register (Port 21xO) 
Table 3-33 


Bit Description 


0-2 Display Mode Field 


000-VGA Mode (Address Decode Disabled) 
001-VGA Mode (Address Decode Enabled) 
010-132-Column Text Mode (Address Decode Disabled) 
011-132-Column Text Mode (Address Decode Enabled) 
100-Extended Graphics Mode 
101 through 111-Reserved 


3 Coprocessor Register Interface Format Field-Determines whether the coprocessor 


uses the Intel or Motorola register format. Setting this bit to 0 selects the Intel format. 
When you select the Intel format, the byte positions of the registers are reversed. The 
only exceptions to this rule are the Direction Steps and the PEL Operations registers. 


4-7 Reserved 


Table 3-34 Aperature control register (Port 21xlh) 


Bit Description 


0-1 Aperture size and Location Field 


00-No 64K Aperfure 
01-64K Aperfure at A0000h 
10-64K Aperfure at B0000h 
11-Reserved 


2-7 Reserved 


Interrupt enable register (Port 21x4h) 


Table 3-36 


Bit Description 


0 Start of Blanking Enable-Setting this field to 1 enables the start of blanking interrupt. 


1 Start of picture Enable-Setting this field to 1 enables the start of picture interrupt. 


2 Sprite Display complete Enable-Setting this field to 1 enables the sprite display 


complete interrupt. 


3-5 Reserved 


6 Coprocessor Access Rejected Enable-Setting this field to 1 enables the coprocessor 


access rejected interrupt. 


7 Coprocessor operation complete Enable-Setting this field to 1 enables the 


coprocessor operation complete interrupt. 


Interrupt status register (Port 21x5h) 


Bit Description 


0 Start of Blanking-A 1 indicates that start of blanking occurred. 


1 Start of picture-A 1 indicates that start of picture occurred. 


2 Sprite Display complete-A 1 indicates that sprite display generation is complete. 


3-5 Reserved 


6 Coprocessor Access Rejected-A 1 indicates that a process tried to access the 


coprocessor and failed. 


7 Coprocessor operation complete-A 1 indicates that a process tried to access the 


coprocessor and succeeded. It also indicates that the coprocessor carried out the 
operation successfully. 


Virtual memory control register (Port 21x6h) Table 3-37 


Bit Description 


0 Enable virtual Address Lookup-This field controls the virtual memory address 


translation function. If you don't set this bit, there are a number of conditions that 
must exist including: all bit maps must be resident, the PEL map addresses represent 
physical locations, the cobrocessor must generate physical addresses, and nonpaged 
operating systems are supported. 


1 Reserved 


2 User/Supervisor selection-When set to 1 , the current process is operating a 


privilege level 3 (user). 


3-5 Reserved 


6 Virtual Memory protection violation Interrupt Enable-Setting this bit to 1 allows the 


adapter to send an interrupt to the system processor when it detects a protection 
violation. 


7 Virtual Memory page Not present Interrupt-Setting this bit to 1 allows the adapter to 


send an interrupt to the system processor when it needs a memory page read from disk. 


Virtual memory interrupt status register (Port 21x7h) Table 3-38 


Bit Description 


0-5 Reserved 


6 Virtual Memory protection violation-This bit is set when a protection error occurs. 


You reset this bit to 0 by writing a 1 to it. Once you reset the bit, the adapter retries 
the page translation that caused the error. If the process does not repair the fault 
condition prior to resetting the bit, then the adapter generates another interrupt. 


7 Virtual Memory page Not present-This bit is set when the adapter detects that it 


needs a page of memory read from disk. You reset this bit to 0 by writing a 1 to it. 
Once you reset the bit, the adapter looks for the page in memory again. If the process 
does not read the page of memory from disk prior to resetting the bit, then the 
adapter generates another interrupt. 


Aperature index register (Port 21x8h) Table 3-39 


Bit Description 


0-5 Aperture Index-Defines the position of the 64K or lMB window within the range of 


memory installed on the adapter. All six bits are used for a 64K windows. The lMB 
windows only uses bits 4 and 5. IVou must write 0 to bits 0 through 3 when using the 
lMB aperture size.) 


6-7 Reserved 


Table 3-40 Memory accessmode register (Port 21x9h) 


Table 3-41 


Bit Description 


0-2 PEL size-Determines the size of the PEL. 


000-1 bit 
001-2 bits 
0104 bits 
011-8 bits 
100-16 bits 
101 through 111-Reserved 


3 PEL order-Controls the ordering method used for the pELs.1 


selects Intel ordering, while 0 selects Motorola ordering. 


4-7 Reserved 


The index register (Port 21xAh) allows you to indirectly access a 
number of registers as well. Data registers (Port 21xB through 
21xFh) allow you to read and write the indexed registers. You 
can access the data using byte, word, or double word values. 
Table 3-41 provides a list of these registers. 


Index register (Port 21xAh) 


Index Value 


Ooh-03h 
04h 
05h-OBh 
Och 
ODh 
OEh-OFh 
10h 
llh 
12h 
13h 
14h 
15h 
16h 
17h 
18h 
19h 
lAh 
lBh 
lch 
lDh 
lEh 
lFh 


Description 


Reserved 
Auto-Configuration 
Reserved 
Coprocessor Save/Restore Data A 
Coprocessor Save/Restore Data 8 
Reserved 
Horizontal Total Low 
Horizontal Total High 
Horizontal Display End Low 
Horizontal Display End High 
Horizontal Blanking Start Low 
Horizontal Blanking Start High 
Horizontal Blanking End Low 
Horizontal Blanking End High 
Horizontal Sync Pulse Start Low 
Horizontal Sync Pulse Start High 
Horizontal Sync Pulse End Low 
Horizontal Sync Pulse End High 
Horizontal Sync Position 
Reserved 
Horizontal Sync Position 
Reserved 


Index Value 


20h 
21h 
22h 
23h 
24h 
25h 
26h 
27h 
28h 
29h 
2Ah 
2Bh 
2Ch 
2Dh 
2Eh-2Fh 
30h 
31h 
32h 
33h 
34h 
35h 
36h 
37h 
38h 
39h 
3Ah 
3Bh 
3Ch 
3Dh 
3Eh-3Fh 
40h 
41h 
42h 
43h 
44h 
45h-4Fh 
50h 
51h 
52h 
53h 
54h 
55h 
56h-5Fh 
60h 
61h 
62h 
63h 
64h 
65h 


Description 


Vertical Total Low 
Vertical Total High 
Vertical Display End Low 
Vertical Display End High 
Vertical Blanking Start Low 
Vertical Blanking Start High 
Vertical Blanking End Low 
Vertical Blanking End High 
Vertical Sync Pulse Start Low 
Vertical Sync Pulse Start High 
Vertical Sync Pulse End 
Reserved 
Vertical Line Compare Low 
Vertical Line Compare High 
Reserved 
Sprite Horizontal Start Low 
Sprite Horizontal Start High 
Sprite Horizontal Preset 
Sprite Vertical Start Low 
Sprite Vertical Start High 
Sprite Vertical Preset 
Sprite Control 
Reserved 
Sprite Color 0 Red 
Sprite Color 0 Green 
Sprite Color 0 Blue 
Sprite Color 1 Red 
Sprite Color 1 Green 
Sprite Color 1 Blue 
Reserved 
Display PEL Map Offset Low 
Display PEL Map Offset Middle 
Display PEL Map Offset High 
Display PEL Map Width Low 
Display PEL Map Width High 
Reserved 
Display Control 1 
Display Control 2 
Display ID and Comparator 
Reserved 
Clock Frequency Select 1 
Boarder Color 
Reserved 
Sprite/Palette Index Low 
Sprite Index High 
Sprite/Palette Prefetch Index Low 
Sprite Prefetch Index High 
Palette Mask 
Palette Data 
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Index Value 


66h 
67h 
68h 
69h 
6Ah 
6Bh 
6Ch-6Fh 
70h 


Description 


Palette Sequence 
Palette Red Prefetch 
Palette Green Prefetch 
Palette Blue Prefetch 
Sprite Data 
Sprite Prefetch 
Reserved 
Clock Frequency Select 2 


GPI functions 


The Graphics Programming Interface (GPI) functions provide the 
programmer with everything needed to work with the display and 
other devices like printers and plotters. Think of the GPI functions as 
the detailed tools that work outside the purview of windows. They 
work with windows, but not within the confines of windows. These 
functions are very device and as a result presentation space oriented. 
In most cases, they also provide a higher level of accuracy than their 
WIN counterparts (where counterparts exist). 


There are three essential function areas: drawing, graphics 
management, and translation. The drawing functions further divide 
into five areas: lines, patterned areas, text, marker symbols, and 
images. The drawing functions allow you to create and shade the 
images that you want to display and save. The graphics 
management functions allow you to control devices, save your data 
to disk, and perform other necessary functions. The translation 
functions allow you to transform one set of image characteristics 
for another. For example, you might want to change the unit of 
measurement from twipps to inches. When combined, all three 
areas allow you total control over the drawing device. This device 
could be anything: memory, the display, a printer, or any other 
physical medium. The combination of device independent function 
calls and translation utilities allow you to work in the graphics 
environment without worrying about the ultimate destination of 
your graphic images. 


The GPI functions are only the start of your programmer's tool kit. 
You require other functions to get any real work done; the GPI 
functions merely embody the part of your program the user sees. 
Table 3-42 contains a complete list of the GPI functions. It includes 
the calling syntax, a brief description of what task the function 
performs, and descriptions of each variable that the function requires. 


GPI function listing 
Table 3-42 


Function 


Ichanged = 
GpiAnimatepalette 
(hpal, ulFormat, 
ulstart, ulcount, 
aulTable) 


fsuccess = 
GpiAssociate 
(hps, hdc) 


Description 


The GpiAnimatepalette function changes the color values of 
animating indexes in a palette. An animating index is one that has 
the PC_RESERVED flag set. Ichanged contains the number of 
remapped colors or an error code on return from the function call. 
hpal contains a palette handle. ulFormat contains the format of 
entries in the table. ulstart contains the starting index. ulcount 
contains the number of elements in aulTable. aulTable contains the 
start of the application data area. GpiAnimatepalette returns one of 
the following values: 
-1 PAL ERROR 
Other Num-ber of remapped colors 


You can retrieve the last error using WinGetLastError. These errors 
include: 


Ox203E 
0x2054 
0x2055 
0x2058 
0x2085 
0x2092 
0x2 1 1 1 
0x2112 


PMERR INSUFFICIENT MEMORY 
PMERR-INV COLOR D-AHA 
PMERR-INV-COLOR-FORMAT 
PMERR-INV-COLOR-START INDEX 
PMERR-INV-IN AREA 
PMERR-INV-LE-NGTH OR COUNT 
PMERR-INV-HPAL 
PMERR-PAL-ETTE BUSY 


The GpiAssociate function associates a graphics presentation space 
with a device context. You also can use this function to disassociate 
the presentation space by using a null handle. fsuccess contains 
true if this function is successful. hps contains a presentation space 
handle. hdc contains a device context handle. You can retrieve the 
last error using WinGetLastError. These errors include: 


Ox2005 PMERR AREA INCOMPLETE 
0x2017 PMERR-DC IS-ASSOCIATED 
0x207C PMERR-INV-H-DC 
0x207F PMERR-INV-HPS 
0x20AI PMERR-INV-MICROPS FUNCTION 
0x20EC PMERR-PAT-H INCOMP-LETE 
0x20F4 PMERR-PS B0SY 
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Function 


fsuccess = 
GpiBeginArea (hps, 
floptions) 


fsuccess = 
GpiBeginElement 
(hps, lType, 
pszDesc) 


fsuccess = 
GpiBeginpath 
(hps, lpath) 


lHits = GpiBitBlt 
(hpsTarget, 
hpssource, lcount, 
aptlpoints, lBop, 
floptions) 


Description 


Ox20F5 PMERR PS IS ASSOCIATED 
Ox2OF7 PMERR-REALrzE NOT suppORT 


The GpiBeginArea function begins the construction of an area. 
fsuccess contains true if this function is successful. hps contains a 
presentation space handle. floptions contains the area options. 
These flags include: BA_NOBOUNDARY, BA_BOUNDARY, 
BA_ALTERNATE, and BA_WINDING. You can retrieve the last 
error using WinGetLastError. These errors include: 


Ox2001 PMERR ALREADY IN AREA 
0x2041 PMERR-INV AREA-CONTROL 
0x207F PMERR-INV-HPS 
0x208B PMERR-INV-IN PATH 
0x20F4 PMERR-PS BUSY 


The GpiBeginElement function defines the start of an element 
within a segment. fsuccess contains true if this function is 
successful. hps contains a presentation space handle. IType contains 
the type to associate with the element. Use the values between 
81000000h and FFFFFFFFh to avoid conflicts with system 
generated elements when starting application-defined elements. 
pszDesc contains a variable-length string that describes the 
element. You can retrieve the last error using WinGetLastError. 
These errors include: 


Ox2002 PMERR ALREADY IN ELEMENT 
0x2018 PMERR-DESC STR-IN6 TRUNCATED 
0x207F PMERR-INV H-PS 
0x20F4 PMERR-PS BUSY 


The GpiBeginpath function defines the start of a path. fsuccess 
contains true if this function is successful. hps contains a 
presentation space handle. Ipath contains the path identifier (always 
set to a value of 1). You can retrieve the last error using 
WinGetLastError. These errors include : 


Ox2003 PMERR ALREADY IN PATH 
0x207F PMERR-INV HPS 
0x2085 PMERR-INV-IN AREA 
0x20AE PMERR-INV-PA-TH ID 
0x20F4 PMERR-PS BUSY 


The GpiBitBlt function copies a rectangle of bit-map image data. 
IHits contains the correlation and error indicators. hpsTarget 
contains the target presentation space handle. hpssource contains 
the source presentation space handle. ICount contains the number 
of points (array element pairs) in aptlpoints. Providing three points 
forces GpiBitBlt to use a source rectangle that matches the target 


Function 


lHits = GpiBox (hps, 
lcontrol, pptlpoint, 
IHBound, lvBound) 


Description 


rectangle in size. When you supply four points, GpiBitBlt performs 
any required stretching or compression. aptlpoints contains an array 
of coordinate pairs. The pairs appear in the following order: Txl, 
Tyl, Tx2, Ty2, Sxl, Syl, Sx2, and Sy2. The first set of coordinates 
refers to the lower-left corner, while the second set refers to the 
upper-right corner. IBop contains the mixing function required. 
There are fifteen different mixing actions including: 
ROP_SRCCOPY, ROP_SRCPAINT, ROP_SRCAND , 
ROP_SRCINVERT, ROP_SRCERASE, ROP_NOTSRCCOPY, 
ROP_NOTSRCERASE, ROP_MERGECOPY, ROP_MERGEPAINT, 
ROP_PATCOPY, ROP_PATPAINT, ROP_PATINVERT, 
ROP_DSTINVERT, ROP_ZERO, and ROP_ONE. floptions 
contains a list of applicable options. You can use bits 15 through 31 
for unique modes supported by particular devices. Other values for 
this parameter include: BBO_OR, BOO_AND, and BBO_IGNORE. 
GpiBitBlt returns one of the following values: 


0000 GPI ERROR 
0001 GPI_OK 
0002 GPI_HITS 


You can retrieve the last error using WinGetLastError. These errors 
include: 


Ox200A PMERR BITMAP NOT FOUND 
0x203A PMERR-INCOME-ATIBL-E BITMAP 
0x203C PMERR-INCORRECT D5 TYPE 
0x2046 PMERR-INV BITBLT-MIX- 
Ox2047 PMERR-INV-BITBLT-STYLE 
0x205B PMERR-INV-COORD-INATE 
0x207F PMERR-INV-HPS 
0x2092 PMERR-INV-LENGTH OR COUNT 
0x20BD PMERR-INV-RECT 
0x20E4 PMERR-NO-BITMAP SELECTED 
0x20F4 PMERR-PS -BUSY 


The GpiBox function draws a rectangular box using the current 
cursor position for one corner and a designated coordinate for the 
opposing corner. IHits contains the correlation and error indicators. 
hps contains a presentation space handle. IControl contains the 
outline and fill control. These values include: DRO_FILL, 
DRO_OUTLINE, and DRO_OUTLINEFILL. pptlpoint contains the 
coordinates of the second corner. IHBound is the horizontal length 
of the ellipse used for rounding at each corner. IVBound is the 
vertical length of the ellipse used for rounding at each corner. 
GpiBox returns one of the following values: 


0000 GPI ERROR 
0001 GPI_OK 
0002 GPI_HITS 
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Function 


lHits = 
Gpicallsegment- 
Matrix (hps, 
lsegment, lcount 
pmatlfArray, 
loptions) 


lHits = Gpicharstring 
(hps, lcount, 
pchstring) 


Description 


You can retrieve the last error using WinGetLastError. These errors 
include: 


Ox2049 PMERR INV BOX CONTROL 
0x204A PMERR-INV-BOX-ROUNDING PARM 
0x205B PMERR-INV-COO-RDINATE 
0x207F PMERR-INV-HPS 
0x20F4 PMERR-PS BUSY 


The GpicallsegmentMatrix function calls a segment and applies an 
instance transform to it. IHits contains the correlation and error 
indicators. hps contains a presentation space handle. Isegment 
contains the identifier of the segment that you want to call. ICount 
contains the number of elements in pmatlfArray. If lcount contains 
a value less than 9, the remaining elements in pmatlfArray default to 
the corresponding elements in the identity matrix. (The function 
defaults to the identfty matrix if lcount contains a value of zero.) 
pmatlfArray contains an instance of the transform matrix. Elements 
three, six, and nine must contain 0, 0, and 1 respectively. IOptions 
contains the transform options. These options include: 
TRANSFORM_REPIACE, TRANSFORM_ADD , and 
TRANSFORM_PREEMPT. GpicallsegmentMatrix returns one of 
the following values: 


0000 GPI ERROR 
0001 GPI_OK 
0002 GPI_HITS 


You can retrieve the last error using WinGetLastError. These errors 
include: 


Ox200D PMERR CALLED SEG IS CHAINED 
0x200E PMERR-CALLED-SEG-IS-CURRENT 
0x200F PMERR-CALLED-SEG-NOT FOUND 
0x207F PMERR-INV HPS- 
Ox2092 PMERR-INV-LENGTH OR COUNT 
0x209B PMERR-INV-MATRIX -ELEMENT 
0x20AI PMERR-INV-MICROP-S FUNCTION 
0x20C7 PMERR-INV-SEG NAM-E 
ox2oDo PMERR-INv-TRA-NSFORM rvpE 
0x20F4 PMERR-PS BUSY 
Ox2OFc PMERR-sEa GALL STACK EMPTy 


The Gpicharstring function draws a character string starting at the 
current cursor position. IHits contains the correlation and error 
indicators. hps contains a presentation space handle. ICount 
contains the number of characters in pchstring. pchstring contains 
the string you want to draw. Gpicharstring returns one of the 
following values: 


Function 


lHits = 
GpicharstringAt 
(hps, pptlpoint, 
lcount, pchstring) 


lHits = 
Gpicharstringpos 
(hps, prclBect, 
floptions, lcount, 
pchstring, alAdx) 


Description 


0000 GPI ERROR 
0001 GPI_OK 
0002 GPI_HITS 


You can retrieve the last error using WinGetLastError. These errors 
include: 


Ox202D PMERR FONT AND MODE MISMATCH 
0x207F PMERR-INV H-PS 
0x2092 PMERR-INV-LENGTH OR COUNT 
0x20F4 PMERR-PS BUSY 


The GpicharstringAt function draws a character string starting at 
the specified cursor position. IHits contains the correlation and error 
indicators. hps contains a presentation space handle. pptlpoint 
contains the coordinates of the starting position. ICount contains the 
number of characters in pchstring. pchstring contains the string 
you want to draw. GpicharstringAt returns one of the following 
values: 


0000 GPI ERROR 
0001 GPI_OK 
0002 GPI_HITS 


You can retrieve the last error using WinGetLastError. These errors 
include: 


Ox202D PMERR FONT AND MODE MISMATCH 
0x205B PMERR-INV C-OORblNATE 
0x207F PMERR-INV-HPS 
0x2092 PMERR-INV-LENGTH OR COUNT 
0x20F4 PMERR-PS BUSY 


The Gpicharstringpos function draws a character string starting at 
the current cursor position. It includes formatting. IHits contains the 
correlation and error indicators. hps contains a presentation space 
handle. prclBect defines the rectangle that bounds the characters 
you draw. It is used to provide a background color for the text. 
OS/2 ignores this parameter unless you use the CHS_OPAQUE or 
CHS_CLIP options. floptions contains the formatting flag. These 
flags include: CHS_OPAQUE, CHS_VECTOR, CHS_LEAVEPOS, 
CHS_CLIP, CHS_UNDERSCORE, and CHS_STRIKEOUT. ICount 
contains the number of characters in pchstring. pchstring contains 
the string that you want to draw. alAdx contains the increment 
values in world coordinates. This controls the spacing between 
characters. OS/2 treats any negative values as zeros. 
Gpicharstringpos returns one of the following values: 


0000 GPI ERROR 
0001 GPI_OK 
0002 GPI_HITS 
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Function 


IHits = 
GpicharstringposAt 
(hps, pptlstart, 
prclBect, floptions, 
lcount, pchstring, 
alAdx) 


fsuccess = 
GpicloseFigure (hps) 


Description 


You can retrieve the last error using WinGetLastError. These errors 
include: 


Ox202D 
0x204E 
0x207F 
0x2092 
0x20BD 
0x20F4 


PMERR FONT AND MODE MISMATCH 
PMERR-INV C-HAR -POS OPTIONS 
PMERR-INV-HPS 
PMERR-INV-LENGTH OR COUNT 
PMERR-INV-RECT 
PMERR-PS BUSY 


The GpicharstringposAt function draws a character string starting 
at the specified cursor position. It includes formatting. IHits contains 
the correlation and error indicators. hps contains a presentation 
space handle. pptlstart contains the coordinates of the starting 
position. prclBect defines the rectangle that bounds the characters 
that you draw. It is used to provide a background color for the text. 
OS/2 ignores this parameter unless you use the CHS_OPAQUE or 
CHS_CLIP options. floptions contains the formatting flag. These 
flags include: CHS_OPAQUE, CHS_VECTOR, CHS_LEAVEPOS, 
CHS_CLIP, CHS_UNDERSCORE, and CHS_STRIKEOUT. ICou nt 
contains the number of characters in pchstring. pchstring contains 
the string that you want to draw. alAdx contains the increment value 
in world coordinates. This controls the spacing between characters. 
OS/2 treats any negative values as zeros. GpicharstringposAt 
returns one of the following values: 


0000 GPI ERROR 
0001 GPI-OK 
0002 GPI_HITS 


You can retrieve the last error using WinGetLastError. These errors 
include: 


Ox202D 
0x204E 
0x205B 
0x207F 
0x2092 
0x20BD 
0x20F4 


PMERR FONT AND MODE MISMATCH 
PMERR-INV C-HAR -POS OPTIONS 
PMERR-INV-COOR-DINAFE 
PMERR-INV-HPS 
PMERR-INV-LENGTH OR COUNT 
PMERR-INV-RECT 
PMERR-PS BUSY 


The GpicloseFigure function closes a figure within a path 
specification. fsuccess contains true if this function is successful. 
hps contains a presentation space handle. You can retrieve the last 
error using WinGetLastError. These errors include: 


Ox207F PMERR INV HPS 
0x20F4 PMERR-PS BUSY 


Function 


fsuccess = 
Gpiclosesegment 
(hps) 


lcomplexity = 
GpicombineBegion 
(hps, hrgnDest, 
hrgnsrcl , hrgnsrc2, 
lmode) 


fsuccess = 
Gpicomment (hps, 
ILength, pbData) 


fsuccess = 
Gpiconvert (hps, 
lsrc, lTarg, lcount 


Description 


The Gpiclosesegment function closes the current segment. 
fsuccess contains true if this function is successful. hps contains a 
presentation space handle. You can retrieve the last error using 
WinGetLastError. These errors include : 


Ox2004 
0x207F 
0x20A1 
0x20E3 
0x20EC 
0x20F4 


PMERR AREA INCOMPLETE 
PMERR-INV H-PS 
PMERR-INV-MICROPS FUNCTION 
PMERR-Nof IN SEG 
PMERR-PATH-IIfcoMPLETE 
PMERR-PS B0SY 


The GpicombineRegion function combines two regions. The source 
and destination regions must be the same device class. IComplexity 
contains the complexity of the resulting region or an error indicator 
on return from the function call. hps contains a presentation space 
handle. hrgnDest contains the destination handle. You can use one 
of the source destinations for this handle. hrgnsrcl and hrgnsrc2 
contain the source destination handles. IMode determines the 
method of combination. These values include: CRGN_OR, 
CRGN_COPY, CRGN_XOR, CRGN_AND, and CRGN_DIFF. 
GpicombineRegion returns one of the following values: 


0000 RGN ERROR 
0001 RGN-NULL 
0002 RGN-RECT 
0003 RGN-COMPLEX 


You can retrieve the last error using WinGetLastError. These errors 
include: 


Ox2034 
0x207F 
0x2080 
0x20BF 
0x20F4 
0x20F8 


PMERR HRGN BUSY 
PMERR-INV HPS 
PMERR-INV-HRGN 
PMERR-INV-REGION MIX MODE 
PMERR-PS BUSY 
PMERR-RE-GION IS CLIP REGION 


The Gpicomment function adds a comment to the current segment. 
You can use this area to maintain application specific data. 
fsuccess contains true if this function is successful. hps contains a 
presentation space handle. ILength contains the length of the 
comment string. pbData contains the comment string. You can 
retrieve the last error using WinGetLastError. These errors include: 


Ox207F PMERR INV HPS 
0x2092 PMERR-INV-LENGTH OR COUNT 
0x20F4 PMERR-PS BUSY 


The Gpiconvert function converts an array of coordinate pairs from 
one coordinate space to another. fsuccess contains true if this 
function is successful. hps contains a presentation space handle. 


Table 3-42 Continued 


pfiffiRE 


Function 


aptlpoints) 


fsuccess = 
Gpiconvertwith- 
Matrix (hps, ICount, 
aptlpoints, lcount, 
pmatlfArray) 


hmfNew = 
GpicopyMetaFile 
(hmf) 


Description 


lsrc contains the source coordinate space. ITarg contains the target 
coordinate space. Valid values for these two parameters include: 
CVTC_WORLD , CVTC_MODEL, CVIC_DEFAULTPAGE, 
CVTC_PAGE, and CVTC_DEVICE. ICount contains the number of 
coordinate pairs. aptlpoints is an array of coordinate pairs. You can 
retrieve the last error using WinGetLastError. These errors include: 


Ox2014 
0x207F 
0x205A 
0x205B 
0x2092 
0x20F4 


PMERR COORDINATE OVERFLOW 
PMERR-INV HPS 
PMERR-INV-COORD SPACE 
PMERR-INv-cOORDrNATE 
PMERR-INV-LENGTH OR COUNT 
PMERR-PS BUSY 


The GpiconvertwithMatrix function converts an array of coordinate 
pairs from one coordinate space to another, using the supplied 
transform matrix. fsuccess contains true if this function is 
successful. hps contains a presentation space handle. ICount 
contains the number of coordinate pairs and the number of elements 
in pmatlfArray. If the number of transform matrix elements is less 
than nine, OS/2 defaults to the identity matrix for the remaining 
elements. In addition, it uses the identity matrix if the number of 
elements is zero. aptlpoints is an array of coordinate pairs. 
pmatlfArray contains the transform matrix. Elements 3, 6, and 9 
must be 0, 0, and 1 respectively. You can retrieve the last error 
using WinGetLastError. These errors include: 


Ox2014 PMERR COORDINATE OVERFLOW 
0x205B PMERR-INV COORDIN-ATE 
0x207F PMERR-INV-HPS 
0x2092 PMERR-INV-LENGTH OR COUNT 
0x20F4 PMERR-PS BUSY 


The GpicopyMetaFile function creates a new metafile and copies 
the contents of a metafile that you loaded into memory into it. Only 
the process that creates the metafile can use it. OS/2 automatically 
deletes the metafile when the process terminates. hmfNew contains 
the handle of the new metafile or an error indicator. hmf contains the 
handle of the source metafile. GpicopyMetaFile returns one of 
the following values: 


0000 GPI ERROR 
<>0 New-metafile handle 


You can retrieve the last error using WinGetLastError. These errors 
include: 


Ox207E PMERR INV HMF 
0x20D9 PMERR-METAFILE IN USE 


Function 


lNumHits = 
Gpicorrelatechain 
(hps, IType, pptlpick 
lMaxHits, lMaxDepth 
alsegTag) 


lNumHits = 
GpicorrelateFrom 
(hps, IFirstsegment, 
lsecondsegment, 
lType, pptlpick, 
lMaxHits, lMexDepth, 
alsegTag) 


lNumHits = 
Gpicorrelate 


Description 


Ox2106 PMERR TOO MANY METAFILES IN USE 


The Gpicorrelatechain function compares a segment chain with an 
aperfure. It returns a set of segment and tag pairs whenever the 
segment chain appears within the aperture. INumHits contains the 
number of hits or an error indicator (a value of 0). hps contains a 
presentation space handle. IType contains the segment type. There 
are two values for this parameter: PICKSEL_VISIBLE and 
PICKSEL_ALL. pptlpick contains the center of the aperfure. 
IMaxHits contains the maximum number of hits that alsegTag can 
hold. IMaxDepth contains the number of segment identifier and tag 
pairs that the function returns each hit. alsegTag is an array of 
segment identifier and tag pairs. You can retrieve the last error using 
WinGetLastError. These errors include : 


Ox205B 
0x205C 
0x205D 
0x207F 
0x209C 
0x20A1 
0x20F4 


PMERR INV COORDINATE 
PMERR-INV-CORRELATE DEPTH 
PMERR-INV-CORRELATE-TYPE 
PMERR-INV-HPS 
PMERR-INV-MAX HITS 
PMERR-INV-MICR-OPS FUNCTION 
PMERR-PS BUSY 


The GpicorrelateFrom function compares a segment chain with an 
aperture. It returns a set of segment and tag pairs whenever the 
segment chain appears within the aperture. INumHits contains the 
number of hits or an error indicator (a value of 0). hps contains a 
presentation space handle. IFirstsegment contains the first segment 
that you want to compare. ILastsegment contains the last segment 
you want to compare. IType contains the segment type. There are 
two values for this parameter: PICKSEL_VISIBLE and 
PICKSEL_ALL. pptlpick contains the center of the aperture. 
IMaxHits contains the maximum number of hits that alsegTag can 
hold. IMaxDepth contains the number of segment identifier and tag 
pairs that the function returns each hit. alsegTag is an array of 
segment identifier and tag pairs. You can retrieve the last error using 
WinGetLastError. These errors include : 


Ox205B 
0x205C 
0x205D 
0x207F 
0x209C 
0x20A1 
0x20C8 
0x20F4 
0x20FF 
0x2100 


PMERR INV COORDINATE 
PMERR-INV-CORRELATE DEPTH 
PMERR-INV-CORRELATE-TYPE 
PMERR-INV-HPS 
PMERR-INV-MAX HITS 
PMERR-INV-MICR-OPS FUNCTION 
PMERR-INV-SEG NAM-E 
PMERR-PS BUSY- 
pMERR-sEa NOT CHAINED 
PMERR-SEG-NOT-FOUND 


The Gpicorrelatesegment function compares a segment with an 
aperture. It returns a set of segment and tag pairs whenever the 
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Function 


Segment (hps, 
lsegment, lType, 
pptlpick, lMaxHits 
IMaxDepth, 
alsegTag) 


hbm= 
GpicreateBitmap 
(hps, pbmp2New, 
floptions, pblnitData, 
pbmi2lnfoTable) 


fsuccess = 
GpicreateLogcolor- 
Table (hps, floptions, 
lFormat, lstart, 
lcount, alTable) 


Description 


segment chain appears within the aperture. INumHits contains the 
number of hits or an error indicator (a value of 0). hps contains a 
presentation space handle. Isegment contains the identifier of the 
segment that you want to compare. IType contains the segment 
type. There are two values for this parameter: PICKSEL_VISIBLE 
and PICKSEL_ALL. pptlpick contains the center of the aperture. 
IMaxHits contains the maximum number of hits that alsegTag can 
hold. IMaxDepth contains the number of segment identifier and tag 
pairs that the function returns each hit. alsegTag is an array of 
segment identifier and tag pairs. You can retrieve the last error using 
WinGetLastError. These errors include: 


Ox205B 
0x205C 
0x205D 
0x207F 
0x209C 
0x20A1 
0x20C8 
0x20F4 
0x2100 


PMERR INV COORDINATE 
PMERR-INV-CORREIAIE DEPTH 
PMERR-INV-CORRELATE-TYPE 
PMERR-INV-HPS 
PMERR-INV-MAX HITS 
PMERR-INV-MICR-OPS FUNCTION 
PMERR-INV-SEG NAM-E 
PMERR-PS BUSY- 
pMERR-sEa NOT FOuND 


The GpicreateBitmap function creates a bit map and returns a 
handle to it. hbm contains bitmap handle (0 for an error condition). 
hps contains a presentation space handle. pbmp2New contains the 
bitmap information header that defines the bitmap format. floptions 
contains the CBM_INIT bitmap option. You can initialize bits 16 
through 31 with any options supported by a specific device driver. 
pbl nitData contains the initialization data when you set CBM_INIT 
in floptions. pbmi2lnfoTable contains the bitmap information table 
that defines the format of pblnitData. You can retrieve the last error 
using WinGetLastError. These errors include: 


Ox207F PMERR INV HPS 
0x208F PMERR-INV-INFO TABLE 
0x20F4 PMERR-PS BUSY 


The GpicreateLogcolorTable function defines the entries of a 
logical color table. fsuccess contains true if this function is 
successful. hps contains a presentation space handle. floptions 
contains one of the following options: LCOL_RESET and 
LCOL PURECOLOR. IFormat determines the format of the table 
entries-including: LCOLF_INDRGB, LCOLF_CONSECRGB, and 
LCOLF_RGB. Istart contains the starting index when using the 
LCOLF CONSECRGB format. ICount contains the number of 
entries iL alTable. alTable contains the color table definition data. 
You can retrieve the last error using WinGetLastError. These errors 
include: 


Function 


lMatch = 
GpicreateLogFont 
(hps, pName, ILcid, 
pAttrs) 


hpal = 
Gpicreatepalette 
(hab, floptions, 
IFormat, ICount, 
alTable) 


Description 


Ox2054 
0x2055 
0x2057 
0x2058 
0x207F 
0x2092 
0x20F4 
0x20F6 
0x210F 


PMERR INV COLOR DATA 
PMERR-INV-COLOR-FORMAT 
PMERR-INV-COLOR-OPTIONS 
PMERR-INV-COLOR-START INDEX 
PMERR-INV-HPS 
PMERR-INV-LENGTH OR COUNT 
PMERR-PS BUSY 
PMERR-REALIZE NOT SUPPORTED 
PMERR-PALETTE-SELECTED 


The GpicreateLogFont function provides a logical font definition. 
hps contains a presentation space handle. pName contains an 
8-character logical font name. ILcid contains the local identifier in 
the range from 0 (default) to 254. pAttrs is a pointer to the font 
attributes. GpicreateLogFont returns one of the following values: 


0000 GPI ERROR 
0001 FONT DEFAULT 
0002 FONT-MATCH 


You can retrieve the last error using WinGetlrdstError. These errors 
include: 


Ox202F 
0x2072 
0x207F 
0x20CA 
0x20D5 
0x20F4 
0x2102 


PMERR FONT NOT LOADED 
PMERR-INV FbNT ATTRS 
PMERR-INV-HPS 
PMERR-INV-SETID 
PMERR-KER-NING NOT SUPPORTED 
PMERR-PS BUSY 
PMERR-SEFID IN USE 


The Gpicreatepalette function creates and initializes a color palette. 
hpal contains the palette handle (0 for an error condition). hab 
contains the anchor block handle. floptions determines the color 
entry table options including: LCOL_PURECOLOR and 
LCOL_OVERRIDE_DEFAULT_COLORS. I Format specifies the 
color entry table format including: LCOLF_CONSECRGB. ICount is 
the number entries in alTable. alTable is an array of color entries. 
Each entry is a 4-byte integer with the following value: (F x 
16777216) + (fz x 65536) + (G x 256) + 8. F is one of the 
following flags: PC_RESERVED or PC_EXPLICIT. H, G, and 8 are 
the color values. You can retrieve the last error using 
WinGetLastError. These errors include : 


Ox203F 
0x2054 
0x2055 
0x2057 
0x2058 
0x2092 


PMERR INSUFFICIENT MEMORY 
PMERR-INV COLOR D-ATA 
PMERR-INV-COLOR-FORMAT 
PMERR-INV-COLOR-OPTIONS 
PMERR-INV-COLOR-START INDEX 
PMERR-INV-LENGTH OR C-OUNT 


hps = Gpicreateps The Gpicreateps function creates a presentation space. hps 
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Function 


(hab, hdc, psizlsize, 
floptions) 


hrgn = 
GpicreateBegion 
(hps, lcount, 
arclBectangles) 


fsuccess = 
GpiDeleteBitmap 
(hbm) 


fsuccess = 
GpiDeleteElement 
(hps) 


Description 


contains the presentation space handle (0 for an error condition). 
hab contains the anchor block handle. hdc contains the device 
context handle. This is mandatory for a micro presentation space. 
psizlsize contains the presentation space page size. floptions 
contains the presentation space options. There are five fields: 
PS_UNITS, PS_FORMAT, PS_rvpE, PS_MODE, and 
PS_ASSOCIATE. Simply OR the correct values for each field 
together to create the parameter. PS_UNITS includes: 
PU_ARBITRARY, PU_PELS , PU_LOMETRIC, PU_HIMETRIC, 
PU_LOENGLISH, PU_HIENGLISH, and PU_TWIPS. PS_FORMAT 
includes: GPIF_DEFAULT, GPIF_SHORT, and GPIF_LONG. 
PS_TYPE includes: GPIT_NORMAL and GPIT_MICRO. Always 
assume that the PS_MODE entry is 0. PS_ASSOCIATE includes: 
GPIA NOASSOC and GPIA ASSOC. You can retrieve the last 
error Lsing WinGetLastError.-These errors include : 


Ox2017 PMERR DC IS ASSOCIATED 
0x207C PMERR-INV-H-DC 
0x20A9 PMERR-INV-OR INCOMPAT OPTIONS 
0x20BA PMERR-INV-PS -SIZE 


The GpicreateRegion function creates a region for a particular class 
of device using a series of rectangles. hrgn contains the region 
handle (0 for an error condition). hps contains the presentation 
space handle. ICount determines the number of rectangles. 
arclBectangles is an array of rectangles. You can retrieve the last 
error using WinGetLastError. These errors include: 


Ox205B PMERR INV COORDINATE 
0x207F PMERR-INV-HPS 
0x2092 PMERR-INV-LENGTH OR COUNT 
0x20BD PMERR-INV-RECT 
0x20F4 PMERR-PS BUSY 


The GpiDeleteBitmap function deletes a bitmap. fsuccess contains 
true if this function is successful. hbm contains the handle of the 
bitmap you want to delete. You can retrieve the last error using 
WinGetLastError. These errors include : 


Ox2008 PMERR BITMAP IS SELETED 
0x2032 PMERR-HBITMA-P BUSY 
0x207B PMERR-INV HBITMAP 


The GpiDeleteElement function deletes the specified element. 
fsuccess contains true if this function is successful. hps contains 
the presentation space handle. You can retrieve the last error using 
WinGetLastError. These errors include : 


Ox207F PMERR INV HPS 


Function 


fsuccess = 
GpiDeleteElement- 
Bange (hps, 
lFirstElement, 
lLastElement) 


fsuccess = 
GpiDeleteElements- 
BetweenLabels (hps, 
lFirstLabel, 
ILastLabel) 


fsuccess = 
GpiDeleteMetaFile 
(hmf) 


fsuccess = 
GpiDeletepalette 
(hpal) 


Description 


Ox2089 PMERR INV IN ELEMENT 
0x20AI PMERR-INV-MI-CROPS FUNCTION 
Ox2OE2 PMERR-Nor IN RETAIN MODE 
0x20E6 PMERR-NO 5UERENT S-EG 
0x20F4 PMERR-PS -BUSY 


The GpiDeleteElementRange function deletes the specified element 
range. fsuccess contains true if this function is successful. hps 
contains the presentation space handle. IFirstElement and 
lLastElement contain the number of the first and last elements to 
delete. You can retrieve the last error using WinGetLastError. These 
errors include : 


Ox207F 
0x2089 
0x20A1 
0x20E2 
0x20E6 
0x20F4 


PMERR INV HPS 
PMERR-INV-IN ELEMENT 
PMERR-INV-MI-CROPS FUNCTION 
PMERR-Not IN RETAIN MODE 
PMERR-NO euERENT s-EG 
PMERR-PS-BUSY 


The GpiDeleteElementBetweenLabels function deletes the elements 
between the specified labels. fsuccess contains true if this function 
is successful. hps contains the presentation space handle. 
IFirstLabel and lLastLabel contains the labels marking the start and 
end of the range of elements to delete. You can retrieve the last 
error using WinGetLastError. These errors include: 


Ox207F 
0x2089 
0x20A1 
0x20D6 
0x20E2 
0x20E6 
0x20F4 


PMERR INV HPS 
PMERR-INV-IN ELEMENT 
PMERR-INV-MI-CROPS FUNCTION 
PMERR-LAB-EL NOT F-OUND 
PMERR-NOT IIf RET-AIN MODE 
PMERR-NO euERENT s-EG 
PMERR-PS-BUSY 


The GpiDeleteMetaFile function deletes a metafile. fsuccess 
contains true if this function is successful. hmf contains the metafile 
handle that you want to delete. You can retrieve the last error using 
WinGetLastError. These errors include: 


Ox207E PMERR INV HMF 
0x20D9 PMERR-MET-AFILE IN USE 
0x2106 PMERR-TOO MAN-Y ivlETAFILES IN USE 


The GpiDeletepalette function deletes a color palette. fsuccess 
contains true if this function is successful. hpal contains the color 
palette handle that you want to delete. You can retrieve the last error 
using WinGetLastError. These errors include: 


Ox201F PMERR PALETTE SELECTED 
0x2111 PMERR-INV HPA[ 
Ox2112 PMERR-PAL-BITE BUSY 
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Function 


fsuccess = 
GpiDeletesegment 
(hps, lsegid) 


fsuccess = 
GpiDeletese ments 
(hps, IFirstse ment 
lLastsegmen 


fsuccess = 
GpiDeletesetld (hps, 
lLcid) 


fsuccess = 
GpiDestroyps (hps) 


fsuccess = 
GpiDestroypegion 


Description 


The GpiDeletesegment function deletes a retained segment. 
fsuccess contains true if this function is successful. hps contains 
the presentation space handle. Isegid contains the segment 
identification. You can retrieve the last error using WinGetLastError. 
These errors include: 


Ox207F PMERR INV HPS 
0x20AI PMERR-INV-MICROPS FUNCTION 
0x20C8 PMERR-INV-SEG NAM-E 
0x20F4 PMERR-PS gusY- 


The GpiDeletesegments function deletes a range of retained 
segments. fsuccess contains true if this function is successful. hps 
contains the presentation space handle. IFirstsegment and 
ILastsegment contain the first and last segment identifiers in the 
range that you want to delete. You can retrieve the last error using 
WinGetLastError. These errors include: 


Ox207F PMERR INV HPS 
0x20AI PMERR-INV-MICROPS FUNCTION 
0x20C8 PMERR-INV-SEG NAM-E 
0x20F4 PMERR-PS gusY- 


The GpiDeletesetld function deletes a logical font or bitmap tag. 
Bitmaps are simply untagged; the handle to them still is valid. OS/2 
deletes fonts from memory. fsuccess contains true if this function is 
successful. hps contains the presentation space handle. ILcid 
contains the identifier of the object that you want to delete. 
Specifying a value of LCID_ALL deletes all fonts and untags all 
bitmaps. It also restores the original default font. You can retrieve 
the last error using WinGetLastError. These errors include: 


Ox207F PMERR INV HPS 
0x20CA PMERR-INV-SETID 
0x20F4 PMERR-PS BUSY 
0x2102 PMERR-SEFID IN USE 
0x2103 PMERR-SETID-N6T FOUND 


The GpiDestroyps function destroys the presentation space. It also 
destroys any objects owned by the presentation space. fsuccess 
contains true if this function is successful. hps contains the 
presentation space handle. You can retrieve the last error using 
WinGetLastError. These errors include : 


Ox207F PMERR INV_HPS 
0x20F4 PMERR-PS BUSY 
0x20F5 PMERR-PS-IS ASSOCIATED 


The GpiDestroyRegion function destroys a region. fsuccess 
contains true if this function is successful. hps contains the 


Function 


(hps, hrgn) 


lHits = GpiDrawBits 
(hpsTarget, pBits, 
pbmi2lnfoTable, 
lcount, aptlpoints, 
lBop, floptions) 


fsuccess = 
GpiDrawchain (hps) 


Description 


presentation space handle. hrgn contains the region handle that you 
want to destroy. You can retrieve the last error using 
WinGetLastError. These errors include : 


Ox2034 PMERR HRGN BUSY 
0x207F PMERR-INV His 
0x2080 PMERR-INV-HRGN 
0x20F4 PMERR-PS BUSY 
0x20F8 PMERR-RE-GION IS CLIP REGION 


The GpiDrawBits function draws (copies) a rectangle of bits from a 
storage area to the specified device context. IHits contains the 
correlation and error indicators. hpsTarget contains the 
presentation space handle of the target. pBits contains a pointer to 
the source bits (must use a standard bitmap format). pbmi2lnfoTable 
contains a bitmap information table that describes the format of the 
source bits. ICount is always equal to 4. aptlpoints contains an array 
of lcount points. These points are: Txl, Tyl, Tx2, Ty2, Sxl, Syl, 
Sx2, and Sy2. The first set of points is the bottom-left corner. The 
second set of points is the upper-right corner. IBop contains the 
mixing function required. There are 15 different mixing actions 
including : ROP_SRCCOPY, ROP_SRCPAINT, ROP_SRCAND , 
ROP_SRCINVERT, ROP_SRCERASE, ROP_NOTSRCCOPY, 
ROP_NOTSRCERASE, ROP_MERGECOPY, ROP_MERGEPAINT, 
ROP_PATCOPY, ROPPATPAINT, ROP_PATINVERT, 
ROP_DSTINVERT, ROP_ZERO, and ROP_ONE. floptions 
contains a list of applicable options. You can use bits 15 through 31 
for unique modes supported by particular devices. Other values for 
this parameter include: BBO_OR, BOO_AND, and BBO_IGNORE. 
GpiBitBlt returns one of the following values: 


0000 GPI ERROR 
0001 GPI_OK 
0002 GPI-HITS 


You can retrieve the last error using WinGetLastError. These errors 
include: 


Ox203C 
0x2046 
0x2047 
0x205B 
0x207F 
0x2092 
0x20BD 
0x20F4 


PMERR INcoRRECT Dc rvpE 
PMERR-INV BITBLT -MIX- 
PMERR-INV-BITBLT-STYLE 
PMERR-INV-COORD-INATE 
PMERR-INV-HPS 
PMERR-INV-LENGTH OR COUNT 
PMERR-INV-RECT 
PMERR-PS BUSY 


The GpiDrawchain function draws the segments that are in a 
segment chain. fsuccess contains true if this function is successful. 
hps contains the presentation space handle. You can retrieve the 
last error using WinGetLastError. These errors include: 
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Function 


fsuccess = 
GpiDrawDynamics 
(hps) 


fsuccess = 
GpiDrawFrom (hps, 
lFirstsegment, 
lLastsegment) 


fsuccess = 
GpiDrawsegment 
(hps, lsegment) 


lHits = 
GpiElement (hps, 
lType, pszDesc, 
lLength, pbData) 


Description 


Ox207F PMERR INV HPS 
0x20AI PMERR-INV-MICROPS FUNCTION 
0x20F4 PMERR=PS_BUSY 


The GpiDrawDynamics function redraws the dynamic segments 
(segments with the AITR_DYNAMIC segment attribute) in or called 
from the segment chain. fsuccess contains true if this function is 
successful. hps contains the presentation space handle. You can 
retrieve the last error using WinGetLastError. These errors include: 


Ox2074 PMERR INV FOR THIS DC TYPE 
0x207F PMERR-INV-HPS 
0x20AI PMERR-INV-MICROPS FUNCTION 
0x20F4 PMERR-PS BUSY 


The GpiDrawFrom function draws a section of the segment chain. 
fsuccess contains true if this function is successful. hps contains 
the presentation space handle. IFirstsegment and lLastsegment 
contain the identifiers of the first and last segments that you want to 
draw. You can retrieve the last error using WinGetLastError. These 
errors include: 


Ox207F 
0x20A1 
0x20C8 
0x20F4 
0x20FF 
0x2100 


PMERR INV HPS 
PMERR-INV-MICROPS FUNCTION 
PMERR-INV-SEG NAM-E 
PMERR-PS BUSY- 
pMERR-sEa NOT CHAINED 
PMERR-SEG-NOT-FOUND 


The GpiDrawsegment function draws the specified segment. 
fsuccess contains true if this function is successful. hps contains 
the presentation space handle. Isegment contains the identifier of 
the segment that you want to draw. You can retrieve the last error 
using WinGetLastError. These errors include: 


Ox207F PMERR INV HPS 
0x20AI PMERR-INV-MICROPS FUNCTION 
0x20C8 PMERR-INV-SEG NAM-E 
0x20F4 PMERR-PS BUSY- 
Ox2ioo PMERR-sEa NOT FOuND 


The GpiElement function adds a single element to the current 
segment. IHits contains the correlation and error indicators. hps 
contains the presentation space handle. IType contains the type you 
want to associate with the element. Application-defined types should 
use the range 81000000h to FFFFFFFFh to avoid conflict with 
system-generated elements. pszDesc contains a s.tring that 
describes the element. ILength contains the length of the data for 
the element. pbData is a pointer to the buffer containing the data. 


Function 


IHits = GpiEndArea 
(hps) 


fsuccess = 
GpiEndElement 
(hps) 


fsuccess = 
GpiEndpath (hps) 


lEquality = 
GpiEqualBegion 


Description 


GpiElement returns one of the following values: 


0000 GPI ERROR 
0001 GPI_OK 
0002 GPI_HITS 


You can retrieve the last error using WinGetLastError. These errors 
include: 


Ox2002 
0x207F 
0x2092 
0x20A0 
0x20D4 
0x20F4 


PMERR ALREADY IN ELEMENT 
PMERR-INV HPS 
PMERR-INV-LENGTH OR COUNT 
PMERR-INV-MICROPS FU-NCTION 
PMERR-DAT-A TOO L6NG 
PMERR-PS B0SY 


The GpiEndArea function ends the construction of a shaded area. 
OS/2 automatically adds a closing line (if required) before ending the 
construction. IHits contains the correlation and error indicators. hps 
contains the presentation space handle. GpiEndArea returns one of 
the following values: 


0000 GPI ERROR 
0001 GPI_OK 
0002 GPI_HITS 


You can retrieve the last error using WinGetLastError. These errors 
include: 


Ox2014 PMERR COORDINATE OVERFLOW 
0x207F PMERR-INV HPS 
0x20DD PMERR-Nor IN AREA 
0x20F4 PMERR-PS B-USY 


The GpiEndElement function terminates an element started by 
GpiBeginElement. fsuccess contains true if this function is 
successful. hps contains the presentation Space handle. You can 
retrieve the last error using WinGetLastError. These errors include: 


Ox207F PMERR INV HPS 
0x20DF PMERR-NOT IN ELEMENT 
0x20F4 PMERR-PS B-USY 


The GpiEndpath function ends the specification of a path started by 
GpiBeginpath. fsuccess contains true if this function is successful. 
hps contains the presentation space handle. You can retrieve the 
last error using WinGetLastError. These errors include: 


Ox207F PMERR INV HPS 
0x20EI PMERR-Nor IN PATH 
0x20F4 PMERR-PS B-USY 


The GpiEqualRegion function compares to regions of equal device 
class for equality. IEquality contains the equality and error 
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Function 


(hps, hrgnsrcl , 
hrgnsrc2) 


fsuccess = 
GpiErase (hps) 


loft = 
GpiErrorsegment- 
Data (hps, 
plsegment, 
plcontext) 


lcomplexity = 
GpiExcludeclip- 
Bectangle (hps, 
prclBectangle) 


Description 


indicators. hps contains the presentation space handle. hrgnsrcl 
contains the handle of the first region. hrgnsrc2 contains the handle 
of the second region. GpiEqualRegion returns one of the following 
values: 


0000 EQRGN_ERROR 
0001 EQRGN_NOTEQUAL 
0002 EQRGN_EQUAL 


You can retrieve the last error using WinGetLastError. These errors 
include: 


Ox2034 PMERR HRGN BUSY 
0x207F PMERR-INV His 
0x2080 PMERR-INV-HRGN 
0x20F4 PMERR-PS BUSY 
0x20F8 PMERR-RE-GION IS CLIP REGION 


The GpiErase function clears the output area of the device context 
associated with a particular presentation space. It uses the current 
background color and observes all clipping limitations. fsuccess 
contains true if this function is successful. hps contains the 
presentation space handle. You can retrieve the last error using 
WinGetLastError. These errors include : 


Ox207F PMERR INV HPS 
0x20F4 PMERR-PS BUSY 


The GpiErrorsegmentData function returns data about the last 
segment drawing error. This includes the segment name, context, 
and byte offset or element number. loft contains the position of the 
error or an error indicator (a return value of 0). hps contains the 
presentation space handle. plsegment contains the segment in 
which the error occurred. plcontext contains the context of the 
error including: GPIE_SEGMENT, GPIE_ELEMENT, and 
GPIE_DATA. You can retrieve the last error using WinGetLastError. 
These errors include: 


Ox207F PMERR INV HPS 
0x20A0 PMERR-INV-MICROPS FUNCTION 
0x20F4 PMERR-PS BUSY 


The GpiExcludeclipRectangle function excludes the interior of a 
rectangular area from the clipping region. It creates a clipping 
region if one does not exist already. IComplexity contains the 
complexity of clipping or an error indicator. hps contains the 
presentation space handle. prclBectangle contains the coordinates 
of the rectangle that you want to exclude in world coordinates. 
GpiExcludeclipRectangle returns one of the following values: 


Function 


lHits = GpiFillpath 
(hps, lpath, loptions) 


lHits = GpiFloodFill 
(hps, loptions, 
lcolor) 


Description 


0000 RGN ERROR 
0001 RGN-NULL 
0002 RGN-RECT 
0003 RGN-COMPLEX 
You can retrieve the last error using WinGetLastError. These errors 
include: 


Ox205B PMERR INV COORDINATE 
0x207F PMERR-INV-HPS 
0x20BD PMERR-INV-RECT 
0x20F4 PMERR-PS BUSY 
The GpiFillpath function fills the interior of a path using the area 
attributes. It automatically closes any open figures within the path, 
then deletes the path once it completes the task. IHits contains the 
correlation and error indicators. hps contains the presentation space 
handle. Ipath is the identifier of the path that you want to draw 
(always a value of 1). IOptions contains the fill option including: 
FPATH_ALTERNATE and FPATH_WINDING. GpiFillpath returns 
one of the following values: 
0000 GPI ERROR 
0001 GPI_OK 
0002 GPI_HITS 


You can retrieve the last error using WinGetLastError. These errors 
include: 


Ox2070 PMERR INV FILL PATH OPTIONS 
0x207F PMERR-INV-HPS 
0x20AE PMERR-INV-PATH ID 
0x20F4 PMERR-PS BUSY 
0x20FF PMERR-PATH UNKNOWN 
The GpiFloodFill function fills an area bounded by a specific color or 
while on a specific color. The area attributes define the fill. The 
results of this function are very device dependent. IHits contains the 
correlation and error indicators. hps contains the presentation space 
handle. IOptions defines the flood fill options that include: 
FF_BOUNDARY and FF_SURFACE. 1Color contains the boundary 
or surface color. GpiFloodFill returns one of the following values: 
0000 GPI ERROR 
0001 GPI_OK 
0002 GPI_HITS 
You can retrieve the last error using WinGetLastError. These errors 
include: 
Oxl641 PMERR FUNCTION NOT SUPPORTED 
0x203E PMERR-INSUFFICIE-NT M-EMORY 
0x2053 PMERR-INV COLOR A-ITR 
0x207F PMERR-INV-HPS 
0x2085 PMERR-INV-IN AREA 
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Function 


lHits = 
GpiFrameBegion 
(hps, hrgn, 
psizlThickness) 


IHits = GpiFullArc 
(hps, lcontrol, 
fxMultiplier) 


lcount = GpiGetData 
(hps, lsegid, 
ploffset 


Description 


Ox208B PMERR INV IN PATH 
0x20F4 PMERR-PS BUSY 
0x210D PMERR-INV FLOOD FILL OPTIONS 
0x2113 PMERR-STA-RT POIN-T CL-IPPED 
0x2114 PMERR-NO FIL-L 


The GpiFrameRegion function draws a frame within a region using 
the current pattern attributes. IHits contains the correlation and 
error indicators. hps contains the presentation space handle. hrgn 
contains the region handle. psizlThickness contains the thickness of 
the frame. There are two coordinates, one for the X-axis and 
another for the Y-axis. GpiFrameRegion returns one of the 
following values: 


0000 GPI ERROR 
0001 GPI-OK 
0002 GPI-HITS 


You can retrieve the last error using WinGetLastError. These errors 
include: 


Ox2034 PMERR HRGN BUSY 
0x207F PMERR-INV His 
0x2080 PMERR-INV-HRGN 
0x20F4 PMERR-PS BUSY 
0x20F8 PMERR-RE-GION IS CLIP REGION 


The GpiFullArc function draws an arc with the current cursor 
position as its center. IHits contains the correlation and error 
indicators. hps contains the presentation space handle. IControl 
contains the interior and outline control values including: 
DRO_FILL, DRO_OUTLINE, and DRO_OUTLINEFILL. fxMulti pl ier 
determines the size of the arc in relation to an arc with the current 
arc parameters. GpiFulIArc returns one of the following values: 


0000 GPI ERROR 
0001 GPI_OK 
0002 GPI_HITS 


You can retrieve the last error using WinGetLastError. These errors 
include: 


Ox2040 PMERR INV ARC CONTROL 
0x207F PMERR-INV-HPS 
0x20A7 PMERR-INV-MULTIPLIER 
0x20F4 PMERR-PS BUSY 


The GpiGetData function retrieves a set of drawing orders from the 
specified segment and places them in the supplied buffer. ICount 
contains the number of bytes of drawing data returned in pbData or 


Function 


lLength, pbData) 


IHits = Gpilmage 
(hps, lFormat, 
psizllmagesize, 
lLength, pbData) 


lcomplexity = 
Gpilntersectclip- 


Description 


an error indicator (a return value of 0). The drawing information in 
pbData probably is incomplete if lcount equals the value of lLength 
on return from this call. hps contains a handle to the presentation 
space. Isegid contains the segment identifier. ploffset contains the 
segment offset. Always set this value to 0 the first time that you call 
GpiGetData and to the position of the last segment data retrieved on 
subsequent calls. IFormat contains the coordinate type required 
(currently a value of DFORM_NOCONV). ILength is the length of 
the data buffer. pbData contains the drawing data. You can retrieve 
the last error using WinGetLastError. These errors include: 


Ox200F PMERR SEG IS CURRENT 
0x2016 PMERR-DATA Too LONG 
0x2079 PMERR-INV G-ETDA-TA CONTROL 
0x207F PMERR-INV-HPS 
0x2092 PMERR-INV-LENGTH OR COUNT 
0x20AI PMERR-INV-MICROPS FU-NCTION 
0x20C8 PMERR-INV-SEG NAM-E 
0x20C9 PMERR-INV-SEG-OFFSET 
0x20F4 PMERR-PS BUSY- 
Ox2100 PMERR-SEE NOT FOUND 


The Gpilmage function draws a rectangular image with the top-left 
corner at the current cursor position. IHits contains the correlation 
and error indicators. hps contains the presentation space handle. 
IFormat contains the format of the image data (always set to 0). 
psizllmagesize contains the width and height of the image area in 
pels. ILength contains the length of pbData in bytes. pbData 
contains the image data. Each row must contain a multiple of 8 bits. 
For example, if the pel data contains 12-bits, you must pad it to 16. 
The value in lLength must reflect the length of the padded data. 
Gpilmage returns one of the following values: 


0000 GPI ERROR 
0001 GPI_OK 
0002 GPI_HITS 


You can retrieve the last error using WinGetLastError. These errors 
include: 


Ox207F PMERR INV HPS 
0x2082 PMERR-INV-IMAGE DATA LENGTH 
Ox2083 PMERR-INv-IMAGE-DIMErisloN 
Ox2084 PMERR-IRE-IMAGE-FORMAT 
0x20F4 PMERR-PS BUSY 


The GpilntersectclipRectangle function sets the new clip region to 
the intersection of the current clip region and the specified 
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Function 


Bectangle (hps, 
prclBectangle) 


fsuccess = GpiLabel 
(hps, lLabel) 


IHits = GpiLine (hps, 
pptlEndpoint) 


hbm= 


Description 


rectangle. IComplexity contains the complexity of the resulting 
region or an error indicator on return from the function call. hps 
contains a presentation space handle. prclBectangle contains the 
rectangle coordinates in world coordinates. Gpilntersectclip 
Rectangle returns one of the following values: 


0000 RGN ERROR 
0001 RGN-NULL 
0002 RGN-RECT 
0003 RGN-COMPLEX 


You can retrieve the last error using WinGetLastError. These errors 
include: 


Ox205B PMERR INV COORDINATE 
0x207F PMERR-INV-HPS 
0x20BD PMERR-INV-RECT 
0x20F4 PMERR-PS BUSY 


The GpiLabel function generates an element containing a label. 
fsuccess contains true if this function is successful. hps contains 
the presentation space handle. ILabel contains the label that you 
want to assign to the element. You can retrieve the last error using 
WinGetLastError. These errors include: 


Ox207F PMERR INV HPS 
0x2089 PMERR-INV-IN ELEMENT 
0x20AI PMERR-INV-MI-CROPS FUNCTION 
0x20F4 PMERR-PS BUSY 


The GpiLine function draws a line from the current cursor position 
to the specified end point. OS/2 uses the current line color, mix, 
width, and type values. IHits contains the correlation and error 
indicators. hps contains the presentation space handle. 
pptlEndpoint contains the coordinates of the end point of the line. 
GpiEndArea returns one of the following values: 


0000 GPI ERROR 
oool GPI_OK 
0002 GPI_HITS 


You can retrieve the last error using WinGetLastError. These errors 
include: 


Ox205B PMERR INV COORDINATE 
0x207F PMERR-INV-HPS 
0x20A8 PMERR-INV-NESTED FIGURES 
0x20F4 PMERR-PS BUSY 


The GpiLoadBitmap function loads a bitmap from a resource and 


Function 


GpiLoadBitmap (hps, 
Pesource, idBitmap, 
lwidth, lHeight) 


fsuccess = 
GpiLoadFonts (hab, 
pszFilename) 


hmf= 
GpiLoadMetaFile 
(hab, pszFilename) 


fsuccess = 
GpiLoadpublicFonts 
(hab, pszFilename) 


IHits = GpiMarker 
(hps, pptlpoint) 


Description 


returns a handle to it. hbm contains the bitmap handle (or 0 for an 
error condition). hps contains the presentation space handle. 
Besource contains the bitmap identity. It contains NULLHANDLE 
when you want to use the EXE file of the application. idBitmap is 
the identification of the bitmap within the resource file. Iwidth is the 
width of the bitmap in pels. IHeight is the height in pels. OS/2 
stretches the bitmap to fit within lwidth and lHeight; use a value of 
zero to load the bitmap without stretching it. You can retrieve the 
last error using WinGetLastError. These errors include: 


Ox200A PMERR BITMAP NOT FOUND 
0x2047 PMERR-INV BITMAP blMENSION 
0x207F PMERR-INV-HPS 
0x20F4 PMERR-PS BUSY 


The GpiLoadFonts function loads one or more fonts from the 
specified resource file. fsuccess contains true if this function is 
successful. hab contains the anchor block handle. pszFilename 
contains the font filename (OS/2 assumes a EON extension). You 
can retrieve the last error using WinGetLastError. These errors 
include: 


Ox2073 PMERR INV FONT FILE DATA 


The GpiLoadMetaFile function loads data from a file into a metafile. 
hmf contains the metafile handle (a value of 0 signifies an error). 
hab contains the anchor block handle. pszFilename contains the 
filename. You can retrieve the last error using WinGetLastError. 
These errors include: 


Ox2024 PMERR DOSOPEN FAILURE 
0x2025 PMERR-DOSREAD-FAILURE 


The GpiLoadpublicFonts function loads one or more fonts from the 
specified resource file. Any application can use these fonts. 
fsuccess contains true if this function is successful. hab contains 
the anchor block handle. pszFilename contains the font filename 
(OS/2 assumes a EON extension). You can retrieve the last error 
using WinGetLastError. These errors include: 


Ox203F PMERR INSUFFICIENT MEMORY 
0x2073 PMERR-INV FONT FIL-E DATA 


The GpiMarker function draws a marker centered at the specified 
location. IHits contains the correlation and error indicators. hps 
contains the presentation space handle. pptlpoint contains the 
center point coordinates. GpiMarker returns one of the following 
values: 


0000 GPI ERROR 
0001 GPI_OK 
0002 GPI_HITS 
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Function 


fsuccess = 
GpiModifypath (hps, 
Ipath, lMode) 


fsuccess = GpiMove 
(hps, pptlpoint) 


lcomplexity = 
Gpioffsetclippegion 
(hps, pptlpoint) 


Description 


You can retrieve the last error using WinGetLastError. These errors 
include: 


Ox205B PMERR INV COORDINATE 
0x207F PMERR-INV-HPS 
0x20F4 PMERR-PS BUSY 


The GpiModifypath function modifies the specified path. fsuccess 
contains true if this function is successful. hps contains the 
presentation space handle. Ipath contains the path identifier (always 
set to 1). IMode contains the type of modification required 
(MPATH_STROKE is the only valid value). You can retrieve the last 
error using WinGetLastError. These errors include: 


Ox2014 
0x207F 
0x20A6 
0x20AE 
0x20F4 
0x20FF 


PMERR COORDINATE OVERFLOW 
PMERR-INV HPS 
PMERR-INV-MODIFY PATH MODE 
PMERR-INV-PATH ID- 
PMERR-PS BUSY 
PMERR-PATH UNKNOWN 


The GpiMove function moves the cursor from the current position 
to the specified position. fsuccess contains true if this function is 
successful. hps contains the presentation space handle. pptlpoint 
contains the new cursor position in world coordinates. You can 
retrieve the last error using WinGetLastError. These errors include: 


Ox205B PMERR INV COORDINATE 
0x207F PMERR-INV-HPS 
0x20F4 PMERR-PS BUSY 


The GpioffsetclipRegion function moves the clipping region to a 
new position. IComplexity contains the complexity of the resulting 
region or an error indicator on return from the function call. hps 
contains a presentation space handle. pptlpoint contains the 
clipping region position offset in world coordinates. 
GpioffsetclipRegion returns one of the following values: 


0000 RGN ERROR 
0001 RGN-NULL 
0002 RGN-RECT 
0003 RGN-COMPLEX 


You can retrieve the last error using WinGetLastError. These errors 
include: 


Ox2014 PMERR COORDINATE OVERFLOW 
0x207F PMERR-INV HPS 
0x20F4 PMERR-PS BUSY 


fsuccess = 
GpioffsetElement- 
Pointer (hps, loffset) 


fsuccess = 
GpioffsetBegion 
(hps, hrgn, 
pptloffset) 


fsuccess = 
Gpiopensegment 
(hps, lsegment) 


lHits = 
Gpioutlinepath (hps, 


The GpioffsetElementpointer function moves the element pointer 
within the current segment by the specified offset. fsuccess 
contains true if this function is successful. hps contains the 
presentation space handle. Ioffset contains the element position 
offset in world coordinates. You can retrieve the last error using 
WinGetLastError. These errors include : 


Ox207F 
0x2089 
0x20A1 
0x20E2 
0x20E6 
0x20F4 


PMERR INV HPS 
PMERR-INV-IN ELEMENT 
PMERR-INV-MI-CROPS FUNCTION 
PMERR-Nof IN RETAIN MODE 
PMERR-NO euERENT s-EG 
PMERR-PS-BUSY 


The GpioffsetRegion moves a range by the specified offset. 
fsuccess contains true if this function is successful. hps contains 
the presentation space handle. hrgn contains the region handle. 
pptloffset contains the region position offset in world coordinates. 
You can retrieve the last error using WinGetLastError. These errors 
include: 


Ox2034 PMERR HRGN BUSY 
ox2o5B PMERR-Irv c6oRDINATE 
0x207F PMERR-INV-HPS 
0x2080 PMERR-INV-HRGN 
0x20F4 PMERR-PS BUSY 
0x20F8 PMERR-RE-GION IS CLIP REGION 


The Gpiopensegment function opens a segment using the specified 
identification number. fsuccess contains true if this function is 
successful. hps contains the presentation space handle. Isegment 
contains the segment identification number. A value of zero always 
results in a new segment, even if there is one using that identifier. 
However, OS/2 chains zero segments together; you cannot refer to 
a single segment. A positive (nonzero) number creates a new 
retained segment if one that uses that identifier does not exist 
already. If one does exist, OS/2 reopens it in retain mode. You can 
retrieve the last error using WinGetLastError. These errors include: 


Ox2004 PMERR ALREADY IN SEG 
0x2005 PMERR-AREA INC-OM-PLETE 
0x2029 PMERR-DYNA-MIC SEG ZERO INV 
0x207F PMERR-INV HPS 
0x20AI PMERR-INV-MICROPS FUNCTION 
0x20A4 PMERR-INV-MODE FO-R OPEN DYN 
0x20A5 PMERR-INV-MODE-FOR-REOPEN SEG 
0x20C8 PMERR-INV-SEG N~AME 
0x20F4 PMERR-PS BUSY- 
Ox20FC PMERR-PATH INCOMPLETE 
0x2108 PMERR-UNCH-AINED SEG ZERO INV 


The Gpioutlinepath function draws the outline of a path. IHits 
contains the correlation and error indicators. hps contains the 
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Function 


lpath, loptions) 


lHits = 
GpipaintBegion 
(hps, hrgn) 


lHits = GpipartialArc 
(hps, pptlcenter, 
fxMultiplier, 
fxstartAngle, 
fxsweepAngle) 


Description 


presentation space handle. Ipath is the path identifier (always set to 
1). IOptions is reserved (always set to 0). Gpioutlinepath returns 
one of the following values: 


0000 GPI ERROR 
0001 GPI_OK 
0002 GPI_HITS 


You can retrieve the last error using WinGetLastError. These errors 
include: 


Ox207F PMERR INV HPS 
0x20AE PMERR-INV-PATH ID 
0x20CI PMERR-INV-RESERVED FIELD 
0x20F4 PMERR-PS BUSY 
0x20FF PMERR-PATH UNKNOWN 


The GpipaintRegion function pains a region into a presentation 
space using the current pattern attributes. IHits contains the 
correlation and error indicators. hps contains the presentation space 
handle. hrgn contains the region handle. GpipaintRegion returns 
one of the following values: 


0000 GPI ERROR 
0001 GPI_OK 
0002 GPI-HITS 


You can retrieve the last error using WinGetLastError. These errors 
include: 


Ox2034 PMERR HRGN BUSY 
0x207F PMERR-INV HPS 
0x2080 PMERR-INV-HRGN 
0x20F4 PMERR-PS BUSY 
0x20F8 PMERR-RE-GION IS CLIP REGION 


The GpipartialArc function draws a straight line followed by an arc. 
IHits contains the correlation and error indicators. hps contains the 
presentation space handle. pptlcenter contains the center point 
coordinates. fxMultiplier determines the size of the arc in relation to 
an arc with the current arc parameters. fxstartAngle contains the 
start angle in degrees (always positive). fssweepAngle contains the 
sweep angle in degrees (always positive). GpipartialArc returns one 
of the following values: 


0000 GPI ERROR 
oool GPI_OK 
ooo2 GPI_HITS 


You can retrieve the last error using WinGetLastError. These errors 
include: 


Function 


hrgn = 
GpipathTOBegion 
(hps, lpath, 
floptions) 


lHits = 
GpiplayMetaFile 
(hps, hmf, ICountl 
aloptarray, 
plsegcount, 
lcount2, pszDesc) 


Description 


Ox203F 
0x205B 
0x207F 
rJix2!fJA:I 
0x20A8 
0x20F4 


PMERR INV ANGLE PARM 
PMERR-INV-COORD-INATE 
PMERR-INV-HPS 
PMERR-INV-MULTIPLIER 
PMERR-INV-NESTED FIGURES 
PMERR-PS BUSY 


The GpipathTORegion function converts a path to a region. It 
automatically closes any open figures within the path. You cannot 
reuse the path for other purposes once you convert it. hrgn contains 
the region handle (0 for an error condition). hps contains the 
presentation space handle. Ipath contains the path identifier (always 
set to 1). floptions contains the fill options, which include: 
FPATH ALTERNATE and FPATH WINDING. You can retrieve the 
last erro-r using WinGetLastError. T-hese errors include: 


Ox207F PMERR INV HPS 
0x20AE PMERR-INV-PATH ID 
0x20F4 PMERR-PS BUSY 
0x20FF PMERR-PATH UNKNOWN 


The GpiplayMetaFile function plays (executes) a metafile into a 
presentation space. IHits contains the correlation and error 
indicators. hps contains the presentation space handle. hmf 
contains the metafile handle. ICountl contains the number of 
elements in aloptarray. aloptarray contains the options for playing 
the metafile. There are nine fields within aloptarray. The 
PMF_SEGBASE and PMF_RESOIJVE fields are reserved, set them 
to zero. The PMF_LOADTYPE field can contain any of the 
following values: LT_DEFAULT, LT_NOMODIFY and 
LT_ORIGINAI,VIEW. The PMF_LCIDS field can contain any of the 
following values: LC_DEFAULT, LC_NOLOAD, and 
LC_LOADDISC. The PMF_RESET field can contain any of the 
following values: RES_DEFAULT, RES_NORESET, and 
RES_RESET. The PMF_SUPRESS field can contain any of the 
following values: SUP_DEFAULT, SUP_NOSUPPRESS, and 
SUP_SUPPRESS. The PMF_COLORTABLES field can contain any 
of the following values: CTAB_DEFAULT, CTAB_NOMODIFY, 
CIAB_REPLACE, and CTAB_REPIACEPALEITE. The 
PMF_COLORREALIZE field can contain any of the following values: 
CREA_DEFAULT, CREA_DOREALIZE, and CREA_NOREALIZE. 
The PMF_DEFAULTS field can contain any of the following values: 
DDEF_DEFAULT, DDEF_IGNORE, and DDEF_LOADDISC. 
plsegcount is a reserved parameter, OS/2 always sets it to zero. 
ICount2 contains the number of bytes in pszDesc. pszDesc 
contains a descriptive record for the metafile on return from the 
function call. It is always null terminated. GpiplayMetaFile returns 
one of the following values: 


0000 GPI ERROR 
0001 GPI_OK 
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Function 


lHits = GpipointArc 
(hps, aptlpoints) 


lHits = GpipolyFillet 
(hps, lcount, 
aptlpoints) 


Description 


0002 GPI HITS 
You can retrieve the last error using WinGetLastError. These errors 
include: 


Ox203B PMERR INCOMPATIBLE METAFILE 
0x206B PMERR-INV ELEMENT POINTER 
0x207E PMERR-INV-HMF 
0x207F PMERR-INV-HPS 
0x2087 PMERR-INV-IN CURRENT EDIT MODE 
Ox2092 PMERR-INv-LE-NGTH OR -couriT 
0x209D PMERR-INV-METAFILE 
0x20A2 PMERR-INV-MICROPS ORDER 
0x20AC PMERR-INV-OUTSIDE-DRAW MODE 
0x20B8 PMERR-INV-PLAY MEiAFILE-OPTION 
0x20F2 PMERR-PRO-LOG ERROR 
0x20F4 PMERR-PS BUSY- 
Ox2105 PMERR-STOP DRAW OCCURRED 
0x5004 PMERR-DUP 5EG 


The GpipointArc function creates an arc using the current arc 
parameters (through three points) starting at the current cursor 
position. IHits contains the correlation and error indicators. hps 
contains the presentation space handle. aptlpoints contains the 
intermediate and end points. GpipointArc returns one of the 
following values: 


0000 GPI ERROR 
0001 GPI_OK 
0002 GPI_HITS 


You can retrieve the last error using WinGetLastError. These errors 
include: 


Ox205B PMERR INV COORDINATE 
0x207F PMERR-INV-HPS 
0x20A8 PMERR-INV-NESTED FIGURES 
0x20F4 PMERR-PS BUSY 


The GpipolyFillet function draws a curve starting at the current 
position. The curve is defined by the points that you supply. IHits 
contains the correlation and error indicators. hps contains the 
presentation space handle. ICount contains the number of points in 
aptlpoints. aptlpoints contains an array of points. GpipolyFillet 
returns one of the following values: 


0000 GPI ERROR 
oool GPI_OK 
0002 GPI_HITS 


Function 


IHits = 
GpipolyFilletsharp 
(hps, lcount, 
aptlpoints, 
afxsharpness) 


lHits = Gpipolygons 
(hps, lcount, 
alpolygons, loptions, 
IModel) 


Description 


You can retrieve the last error using WinGetLastError. These errors 
include: 


Ox205B PMERR INV COORDINATE 
0x207F PMERR-INV-HPS 
0x2092 PMERR-INV-LENGTH OR COUNT 
0x20A8 PMERR-INV-NESTED -FIGORES 
0x20F4 PMERR-PS BUSY 
The GpipolyFilletsharp function draws a series of connected lines 
starting at the current position. The line endpoints are defined by 
the points you supply. IHits contains the correlation and error 
indicators. hps contains the presentation space handle. ICount 
contains the number of points in aptlpoints. aptlpoints contains an 
array of points. afxsharpness contains an array of sharpness values 
which affect the sharpness of successive fillets. GpipolyFilletsharp 
returns one of the following values: 


0000 GPI ERROR 
0001 GPI-OK 
0002 GPI_HITS 
You can retrieve the last error using WinGetLastError. These errors 
include: 


Ox205B 
0x207F 
0x2092 
0x20A8 
0x20CD 
0x20F4 


PMERR INV COORDINATE 
PMERR-INV-HPS 
PMERR-INV-LENGTH OR COUNT 
PMERR-INV-NESTED-FIGORES 
PMERR-INV-SHARPN-ESS PARM 
PMERR-PS BUSY 


The Gpipolygons function draws a closed set of polygons. IHits 
contains the correlation and error indicators. hps contains the 
presentation space handle. ICount contains the number of polygons 
listed in alpolygons. alpolygons contains an array of polygons. 
IOptions contains a list of drawing options, which include: 
POLYGON_NOBOUNDARY, POLYGON_BOUNDARY, 
POLYGON_ALTERNATE, and POLYGON_WINDING. I Model 
contains the drawing model, which includes: POLYGON_INCL and 
POLYGON_EXCL. Gpipolygons returns one of the following values: 
0000 GPI ERROR 
0001 GPI-OK 
0002 GPI_HITS 


You can retrieve the last error using WinGetLastError. These errors 
include: 


Ox2001 PMERR ALREADY IN AREA 
Ox204i PMERR-Irv AREA-c6NTROL 
0x207F PMERR-INV-HPS 
0x208B PMERR-INV-IN PATH 
0x20F4 PMERR-PS BUSY 
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::_:_:---_:_.-I----_-: 


Function 


lHits = GpipolyLine 
(hps, lcount, 
aptlpoints) 


lHits = 
GpipolyLineDisjoint 
(hps, lcount, 
aptlpoints) 


lHits = 
GpipolyMarker (hps, 
lcount, aptlpoints) 


Description 


The GpipolyLine function draws a series of straight lines starting at 
the current cursor location and connecting the specified points. IHits 
contains the correlation and error indicators. hps contains the 
presentation space handle. ICount contains the number of points in 
aptlpoints. aptlpoints contains an array of points. GpipolyLine 
returns one of the following values: 
0000 GPI ERROR 
0001 GPI_OK 
0002 GPI_HITS 
You can retrieve the last error using WinGetLastError. These errors 
include: 


Ox205B PMERR INV COORDINATE 
0x207F PMERR-INV-HPS 
0x2092 PMERR-INV-LENGTH OR COUNT 
0x20A8 PMERR-INV-NESTED -FIGORES 
0x20F4 PMERR-PS BUSY 
The GpipolyLineDisjoint function draws a series of disjoint straight 
lines using the endpoint pairs that you supply. IHits contains the 
correlation and error indicators. hps contains the presentation space 
handle. ICount contains the number of points in aptlpoints. 
aptlpoints contains an array of points. GpipolyLineDisjoint returns 
one of the following values: 
0000 GPI ERROR 
0001 GPI-OK 
0002 GPI_HITS 
You can retrieve the last error using WinGetLastError. These errors 
include: 


Ox205B PMERR INV COORDINATE 
0x207F PMERR-INV-HPS 
0x2092 PMERR-INV-LENGTH OR COUNT 
0x20A8 PMERR-INV-NESTED -FIGORES 
0x20F4 PMERR-PS BUSY 
The GpipolyMarker function draws markers with their centers at the 
points specified. IHits contains the correlation and error indicators. 
hps contains the presentation space handle. ICount contains the 
number of points in aptlpoints. aptlpoints contains an array of 
points. GpipolyMarker returns one of the following values: 
0000 GPI ERROR 
0001 GPI-OK 
0002 GPI_HITS 


You can retrieve the last error using WinGetLastError. These errors 
include: 


Function 


lHits = Gpipolyspline 
(hps, lcount, 
aptlpoints) 


fsuccess = Gpipop 
(hps, lcount) 


llnside = 
GpiptlnBegion (hps, 
hrgn, pptlpoint) 


Description 


Ox205B PMERR INV COORDINATE 
0x207F PMERR-INV-HPS 
0x2092 PMERR-INV-LENGTH OR COUNT 
0x20F4 PMERR-PS BUSY 


The Gpipolyspline function creates a succession of Bezier splines. 
IHits contains the correlation and error indicators. hps contains the 
presentation space handle. ICount contains the number of points in 
aptlpoints. aptlpoints contains an array of points. Gpipolyspline 
returns one of the following values: 


0000 GPI ERROR 
0001 GPI_OK 
0002 GPI_HITS 


You can retrieve the last error using WinGetLastError. These errors 
include: 


Ox205B PMERR INV COORDINATE 
0x207F PMERR-INV-HPS 
0x2092 PMERR-INV-LENGTH OR COUNT 
0x20A8 PMERR-INV-NESTED -FIGORES 
0x20F4 PMERR-PS BUSY 


The Gpipop function allows you to restore the primitives that you 
saved on the stack. This allows you to reset the previous conditions 
one or more steps at a time. fsuccess contains true if this function 
is successful. hps contains a presentation space handle. ICount 
contains the number of attributes that you want to restore. You can 
retrieve the last error using WinGetLastError. These errors include: 


Ox207F PMERR INV HPS 
0x2092 PMERR-INV-LENGTH OR COUNT 
0x20AI PMERR-INV-MICROP5 FU-NCTION 
0x20F4 PMERR-PS BUSY 
0x20FC PMERR-SE6 CALL STACK EMPTY 


The GpiptlnRegion function checks to see if the specified point is 
within a region. Ilnside contains the inside and error indicators. hps 
contains the presentation space handle. hrgn contains the region 
handle. pptlpoint contains points that you want to check in device 
coordinates. GpiptlnRegion returns one of the following values: 


0000 PRGN ERROR 
0001 PRGN-OUTSIDE 
0002 PRGN-INSIDE 


You can retrieve the last error using WinGetLastError. These errors 
include: 


Ox2034 PMERR HRGN BUSY 
0x205B PMERR-INV COORDINATE 
0x207F PMERR-INV-HPS 
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Function 


lvisibility = 
Gpiptvisible (hps, 
pptlpoint) 


lHits = GpiputData 
(hps, lFormat, 
plLength, pbData) 


fsuccess = 


Description 


Ox2080 PMERR INV HRGN 
0x20F4 PMERR-PS BUSY 
0x20F8 PMERR-RE-GION IS CLIP REGION 


The Gpiptvisible function checks whether a point is visible within 
the clipping region of the device associated with the specified 
presentation space. Ivisibility contains the visibility and error 
indicators. hps contains the presentation space handle. pptlpoint 
contains the point that you want to check in world coordinates. 
Gpiptvisible returns one of the following values: 


0000 PVIS ERROR 
0001 PVIS-INVISIBLE 
0002 PVIS-VISIBLE 


You can retrieve the last error using WinGetLastError. These errors 
include: 


Ox205B PMERR INV COORDINATE 
0x207F PMERR-INV-HPS 
0x20F4 PMERR-PS BUSY 


The GpiputData function passes a buffer of graphics orders to the 
current segment. You also can use it to draw the orders. IHits 
contains the correlation and error indicators. hps contains the 
presentation space handle. IFormat contains the coordinate type 
used including: DFORM_NOCONV, DFORM_S370SHORT, 
DFORM_PCSHORT, and DFORM_PCLONG. plLength contains 
the length of the graphic data in pbData. pbData is a buffer 
containing the orders that you want copied. GpiputData returns one 
of the following values: 


0000 GPI ERROR 
0001 GPI_OK 
0002 GPI_HITS 


You can retrieve the last error using WinGetLastError. These errors 
include: 


Ox206B 
0x207F 
0x2092 
0x20A1 
0x20BB 
0x20C0 
0x20D4 
0x20E8 
0x20F4 


PMERR INV ELEMENT POINTER 
PMERR-INV-HPS 
PMERR-INV-LENGTH OR COUNT 
PMERR-INV-MICROP5 FU-NCTION 
PMERR-INV-PUTDATA-FORMAT 
PMERR-INV-REPLACE-MODE FUNC 
PMERR-DAT-A TOO L6NG 
PMERR-ORDE-R TO-O BIG 
PMERR-PS BUS-Y 


The GpiQueryArcparams function returns the current arc 


Function 


GpiQueryArcparams 
(hps, 
parcpArcparams) 


lMode 
GpiQueryAttrMode 
(hps) 


lDefMask = 
GpiQueryAttrs (hps, 
lprimType, 
flAttrMask, 
ppbunAttrs) 


lcolor - 
GpiQueryBackcolor 
(hps) 


Description 


parameters. This includes full, partial, and 3-point arcs. fsuccess 
contains true if this function is successful. hps contains a 
presentation space handle. parcpArcparams contains the arc 
parameters on function return. You can retrieve the last error using 
WinGetLastError. These errors include: 


Ox2060 PMERR INV DC TYPE 
0x207F PMERR-INV-HP5 
0x208C PMERR-INV-IN RETAIN MODE 
0x20F4 PMERR-PS BUSY 


The GpiQueryAttrMode function returns the current attribute mode 
value (as set by GpisetAttrMode). IMode contains the current 
attribute mode (or 0 to indicate an error). hps contains the 
presentation space handle. You can retrieve the last error using 
WinGetLastError. These errors include : 


Ox207F PMERR INV HPS 
0x20F4 PMERR-PS BUSY 


The GpiQueryAttrs function retrieves the current attributes for the 
specified primitive type. IDefMask returns the defaults mask (values 
can be equal to or greater than 0). A return value of -1 signifies an 
error. hps contains the presentation space handle. IprimType 
contains the primitive type, which includes: PRIM_LINE, 
PRIM_CHAR, PRIM_MARKER PRIM_AREA, and PRIM_IMAGE. 
flAttrMask contains the attributes mask. Each flag that you set 
returns the corresponding flag in lDefMask. If the attribute is not at 
its default value, OS/2 returns it in ppbunAttrs. ppbunAttrs 
contains the attributes that are not at their default value. You can 
retrieve the last error using WinGetLastError. These errors include: 


Ox2060 
0x207F 
0x208C 
0x20B9 
0x20F4 
0x2109 


PMERR INV DC TYPE 
PMERR-IIV-HP5 
PMERR-INV-IN RETAIN MODE 
PMERR-INV-PR-IMITIVE-TYPE 
PMERR-PS BUSY 
PMERR-UN-SUPPORTED AITR 


The GpiQueryBackcolor function returns the current background 
color attribute. IColor contains the background color and error 
indicators. hps contains the presentation space handle. 
GpiQueryBackcolor returns one of the following values: 


0000 CLR ERROR 
-0003 CLR-DEFAULT 
Other Background color index. 


You can retrieve the last error using WinGetLastError. These errors 
include: 


Ox2060 PMERR INV DC TYPE 


Table 3-42 
Continued 


Function 


IColor = 
GpiQueryBackMix 
(hps) 


lscansBeturned = 
GpiQueryBitmapBits 
(hps, lscanstart, 
lscans, pbBuffer, 
pbmi2lnfoTable) 


fsuccess = 
GpiQueryBitmap- 
Dimension (hbm, 
psizlBitmap 
Dimension) 


Description 


Ox207F PMERR INV HPS 
0x208C PMERR-INV-IN RETAIN MODE 
0x20F4 PMERR-PS BUSY 


The GpiQueryBackMix function returns the current background 
color-mixing mode. IColor contains the background color and error 
indicators. hps contains the presentation space handle. 
GpiQueryBackMix returns one of the following values: 


0000 BM DEFAULT 
-0001 BM-ERROR 
>0 Background mix mode. 


You can retrieve the last error using WinGetLastError. These errors 
include: 


Ox2060 PMERR INV DC TYPE 
0x207F PMERR-INV-HP§ 
Ox208C PMERR-INV-IN RETAIN MODE 
0x20F4 PMERR-PS BUSY 


The GpiQueryBitmapBits function returns data from a bitmap and 
places it in application storage. IScansBeturned contains the 
number of scan lines actually returned (values can be equal to or 
greater than 0). A return value of -1 signifies an error. hps contains 
the presentation space handle. IScanstart contains the starting scan 
line number (0 is the bottom line). IScans contains the number of 
scan lines that you want returned. pbBuffer contains the returned 
scan data. pbmi2lnfoTable contains the bitmap information table 
(including the associated color table). You can retrieve the last error 
using WinGetLastError. These errors include: 


Ox2060 
0x207F 
0x208F 
0x2092 
0x20C4 
0x20E4 
0x20F4 


PMERR INV DC TYPE 
PMERR-INV-HP5 
PMERR-INV-INFO TABLE 
PMERR-INV-LENG-TH OR COUNT 
PMERR-INV-SCANST-ART- 
PMERR-NO -BITMA-P SELECTED 
PMERR-PS-BUSY 


The GpiQueryBitmapDimension function returns the height and 
width of the specified bitmap. fsuccess contains true if this function 
is successful. hbm contains the bitmap handle. psizlBitmap 
Dimension contains the size of the bitmap in 0.1 millimeter units. 
You can retrieve the last error using WinGetLastError. These errors 
include: 


Ox2032 PMERR HBITMAP BUSY 
0x207B PMERR-INV HBITiv[AP 


Function 


hbm= 
GpiQueryBitmap- 
Handle (hps, lLcid) 


fsuccess = 
GpiQueryBitmaplnfo- 
Header (hbm, 
pbmp2Data) 


fsuccess = 
GpiQueryBitmap- 
Parameters (hbm, 
pbmpData) 


fsuccess = 
GpiQueryBoundary- 
Data (hps, 
prclBoundary) 


fsuccess = 
GpiQuerycharAngle 
(hps, pgradlAngle) 


Description 


The GpiQueryBitmapHandle function returns the handle of the 
bitmap currently tagged with the specified identifier. hbm contains 
the bitmap handle (0 indicated an error condition). hps contains the 
presentation space handle. ILcid contains the local identifier. You 
can retrieve the last error using WinGetLastError. These errors 
include: 


Ox2036 PMERR ID HAS NO BITMAP 
0x207F PMERR-INV HP5 
0x20CA PMERR-INV-SETID 
0x20F4 PMERR-PS BUSY 


The GpiQueryBitmaplnfoHeader function returns information about 
the bitmap identified by the specified bitmap handle. fsuccess 
contains true if this function is successful. hbm contains the bitmap 
handle. pbmp2Data contains the bitmap information header. You 
can retrieve the last error using WinGetLastError. These errors 
include: 


Ox2032 PMERR HBITMAP BUSY 
0x207B PMERR-INV HBITiv[AP 


The GpiQueryBitmapparameters function returns information about 
the bitmap identified by the bitmap handle. fsuccess contains true 
if this function is successful. hbm contains the bitmap handle. 
pbmpData contains the bitmap information header. You can 
retrieve the last error using WinGetLastError. These errors include: 


Ox2032 PMERR HBITMAP BUSY 
0x207B PMERR-INV HBITMAP 


The GpiQueryBoundaryData function returns the boundary data. 
fsuccess contains true if this function is successful. hps contains 
the presentation space handle. prclBoundary data including the 
following fields: xmin, ymin, xmax, and ymax. You can retrieve the 
last error using WinGetlrdstError. These errors include: 


Ox2014 PMERR COORDINATE OVERFLOW 
0x2060 PMERR-INV DC TYPE- 
Ox207F PMERR-INV-HP5 
0x20F4 PMERR-PS BUSY 
The GpiQuerycharAngle function returns the current value of the 
character baseline angle. fsuccess contains true if this function is 
successful. hps contains the presentation space handle. 
pgradlAngle contains the character baseline angle vector (the 
default is 0, 0). You can retrieve the last error using 
WinGetLastError. These errors include : 


Ox2060 PMERR INV DC TYPE 
0x207F PMERR-INV-HP5 
0x208C PMERR-INV-IN RETAIN MODE 
0x20F4 PMERR-PS BUSY 


Table 3 -42 Continued 


Function 


fsuccess = 
GpiQuerycharBox 
(hps, psizfxsize) 


fsuccess = 
GpiQuerycharBreak- 
Extra (hps, 
pfxBreakExtra) 


lDirection = 
GpiQuerychar- 
Direction (hps) 


fsuccess = 
GpiQuerycharExtra 
(hps, pfxExtra) 


lMode = 
GpiQuerycharMode 


Description 


The GpiQuerycharBox function returns the current value of the 
character box attribute. fsuccess contains true if this function is 
successful. hps contains the presentation space handle. psizlfxsize 
contains the character height and width. You can retrieve the last 
error using WinGetLastError. These errors include: 


Ox2060 PMERR INV DC TYPE 
0x207F PMERR-INV-HP§ 
Ox208C PMERR-INV-IN RETAIN MODE 
0x20F4 PMERR-PS BUSY 


The GpiQuerycharBreakExtra function returns the current value of 
the character-break-extra attribute. fsuccess contains true if this 
function is successful. hps contains the presentation space handle. 
pfxB reakExtra contains the character-break-extra attribute. You can 
retrieve the last error using WinGetLastError. These errors include: 


Ox207F PMERR INV HPS 
0x208C PMERR-INV-IN RETAIN MODE 
0x20F4 PMERR-PS BUSY 


The GpiQuerycharDirection function returns the character direction 
attribute. IDirection contains the character direction and error 
indicators. hps contains the presentation space handle. GpiQuery 
CharDirection returns one of the following values: 


0000 CHDIRN DEFAULT 
-0001 CHDIRN-ERROR 
> 0 Character direction 


You can retrieve the last error using WinGetLastError. These errors 
include: 


Ox2060 PMERR INV DC TYPE 
0x207F PMERR-INV-HP5 
0x208C PMERR-INV-IN RETAIN MODE 
0x20F4 PMERR-PS BUSY 


The GpiQuerycharExtra function returns the current value of the 
character-extra attribute. fsuccess contains true if this function is 
successful. hps contains the presentation space handle. pfxExtra 
contains the character-extra attribute. You can retrieve the last error 
using WinGetLastError. These errors include: 


Ox207F PMERR INV HPS 
0x208C PMERR-INV-IN RETAIN MODE 
0x20F4 PMERR-PS BUSY 


The GpiQuerycharMode function returns the current value of the 
character-mode attribute. I Mode contains the character-mode 


Function 


(hps) 


lLcid = 
GpiQuerycharset 
(hps) 


fsuccess = 
GpiQuerycharshear 
(hps, pptlshear) 


fsuccess = 
GpiQuerycharstring- 
Pos (hps, floptions, 
lcount, pchstring, 
alxincrements, 
aptlpositions) 


Description 


attribute and error indicators. hps contains the presentation space 
handle. GpiQuerycharMode returns one of the following values: 


0000 CM DEFAULT 
-0001 CM-ERROR 
>0 Cha-racter mode 


You can retrieve the last error using WinGetLastError. These errors 
include: 


Ox2060 PMERR INV DC TYPE 
0x207F PMERR-INV-HP5 
0x208C PMERR-INV-IN RETAIN MODE 
0x20F4 PMERR-PS BUSY 


The GpiQuerycharset function returns the character-set local 
identifier (lLcid). ILcid contains the character-set local identifier and 
error indicators. hps contains the presentation space handle. 
GpiQuerycharDirection returns one of the following values: 


0000 LCID DEFAULT 
-0001 LCID-ERROR 
>0 Chara-cter-set local identifier 


You can retrieve the last error using WinGetLastError. These errors 
include: 


Ox2060 PMERR INV DC TYPE 
0x207F PMERR-INV-HP5 
0x208C PMERR-INV-IN RETAIN MODE 
0x20F4 PMERR-PS BUSY 


The GpiQuerycharshear function returns the current 
character-shear angle. fsuccess contains true if this function is 
successful. hps contains the presentation space handle. pptlshear 
contains the character shear angle vector (the default value is 0, 1). 
You can retrieve the last error using WinGetLastError. These errors 
include: 


Ox2060 PMERR INV DC TYPE 
0x207F PMERR-INV-HPS 
0x208C PMERR-INV-IN RETAIN MODE 
0x20F4 PMERR-PS BUSY 


The GpiQuerycharstringpos function processes a string as if you 
drew it using the current character attributes. It returns the drawing 
positions for each character in the string in world coordinates. 
fsuccess contains true if this function is successful. hps contains 
the presentation space handle. floptions contains the option flags, 
which include: CHS VECTOR. ICount contains the number of 
characters in pchstring. pchstring contains the string that you 
want to draw. alxincrements contains the increment values in world 
coordinates. aptlpositions contains an array of points 


Table 3 -42 Continued 


Function 


fsuccess = 
GpiQuerycharstring- 
PosAt (hps, pptlstart, 
floptions, lcount, 
pchstring, 
alxincrements, 
aptlpositions) 


lcomplexity - 
GpiQueryclipBox 
(hps, prclBound) 


Description 


corresponding to each character position. You can retrieve the last 
error using WinGetLastError. These errors include: 


Ox2014 
0x204F 
0x205B 
0x2060 
0x207F 
0x208C 
0x2092 
0x20F4 


PMERR COORDINATE OVERFLOW 
PMERR-INV CHAR PO-S OPTIONS 
PMERR-INV-COOR-DINAiE 
PMERR-INV-DC TYPE 
PMERR-INV-HP5 
PMERR-INV-IN RETAIN MODE 
PMERR-INV-LE-NGTH O-R COUNT 
PMERR-PS BUSY 


The GpiQuerycharstingposAt function processes a string as if you 
drew it using the current character attributes. It returns the drawing 
positions for each character in the string in world coordinates. 
fsuccess contains true if this function is successful. hps contains 
the presentation space handle. pptlstart contains the string starting 
position. floptions contains the option flags which include: 
CHS VECTOR. ICount contains the number of characters in 
pchs-tring. pchstring contains the string that you want to draw. 
alxincrements contains the increment values in world coordinates. 
aptlpositions contains an array of points corresponding to each 
character position. You can retrieve the last error using 
WinGetLastError. These errors include : 


Ox2014 PMERR COORDINATE OVERFLOW 
0x204F PMERR-INV CHAR PO-S OPTIONS 
0x205B PMERR-INV-COOR-DINAFE 
0x2060 PMERR-INV-DC TYPE 
0x207F PMERR-INV-HP5 
0x208C PMERR-INV-IN RETAIN MODE 
0x2092 PMERR-INV-LE-NGTH O-R COUNT 
0x20F4 PMERR-PS BUSY 


The GpiQueryclipBox function returns the dimensions of the 
smallest box that could fit around all the current clipping definitions. 
IComplexity contains the complexity of the resulting region or an 
error indicator. hps contains a presentation space handle. 
ppclBound contains the bounding rectangle dimensions in world 
coordinates. GpiQueryclipBox returns one of the following values: 


0000 RGN ERROR 
0001 RGN-NULL 
0002 RGN-RECT 
0003 RGN-COMPLEX 


You can retrieve the last error using WinGetLastError. These errors 
include: 


Function 


hrgn = 
GpiQueryclipBegion 
(hps) 


IColor = 
GpiQuerycolor (hps) 


fsuccess = 
GpiQuerycolorData 
(hps, lcount, alArray) 


Ilndex 


Querycolorlndex 
s, uloptions 


gbcolor) 


Description 


Ox2014 PMERR COORDINATE OVERFLOW 
0x207F PMERR-INV HPS 
0x20F4 PMERR-PS BUSY 


The GpiQueryclipRegion function returns the handle of the 
currently selected clip region. hrgn contains the region handle (0 
indicates an error). It returns a NULLHANDLE if there is no region 
selected. hps contains the presentation space handle. You can 
retrieve the last error using WinGetLastError. These errors include: 


Ox207F PMERR INV HPS 
0x20F4 PMERR-PS BUSY 


The GpiQuerycolor function returns the current character color 
attribute. IColor contains the background color and error indicators. 
hps contains the presentation space handle. GpiQuerycolor returns 
one of the following values: 


0000 CLR ERROR 
-0003 CLR-DEFAULT 
Other Character color index 


You can retrieve the last error using WinGetLastError. These errors 
include: 


Ox2060 PMERR INV DC TYPE 
0x207F PMERR-INV-HP§ 
Ox208C PMERR-INV-IN RETAIN MODE 
0x20F4 PMERR-PS BUSY 


The GpiQuerycolorData function returns the current logical color 
table or the selected palette. fsuccess contains true if this function 
is successful. hps contains the presentation space handle. ICount 
contains the number of elements in alArray. alArray contains the 
the color information in a set of fields. QCD_LCT FORMAT 
contains one of the following values: LCOLF_DEF-AULT, 
LCOLF_INDRGB, LCOLF_RGB, or LCOLF_PALETTE. 
QCD LCT LOINDEX contains the smallest color index in the color 
table br palttte. QCD_LCT_HIINDEX contains the largest color in 
the color table or palette. QCD_LCT_OPTIONS contains one or 
more of the following values: LCOL_PURECOLOR and 
LCOL_OVERRIDE DEFAULT COLORS. You can retrieve the last 
error using WinGet-hastError. T-hese errors include: 


Ox207F PMERR INV HPS 
0x2092 PMERR-INV-LENGTH OR COUNT 
0x20F4 PMERR-PS BUSY 


The GpiQuerycolorlndex function returns the device color index 
closest to the specified RGB value for the device connected to the 
specified presentation space. IIndex contains the index of the color 
that most closely matches the RGB value (-1 indicates an error). 
hps contains the presentation space handle. uloptions is a reserved 


Table 3 -42 Continued 


Function 


ulcodepage = 
GpiQuerycp (hps) 


fsuccess = 
GpiQuerycurrent- 
Position (hps, 
pptlpoint) 


fsuccess = 
GpiQueryDefArc- 
Params (hps, 
parcpArcparams) 


fsuccess = 
GpiQueryDefAttrs 
(hps, lprimType, 
flAttrMask, 
ppbunAttrs) 


Description 


variable (set to 0). IBgbcolor contains a color in RGB terms. You 
can retrieve the last error using WinGetLastError. These errors 
include: 


Ox2057 PMERR INV COLOR OPTIONS 
0x207F PMERR-INV-HPS 
0x20C3 PMERR-INV-RGBCOLOR 
0x20F4 PMERR-PS BUSY 


The GpiQuerycp function returns the currently selected graphics 
code page (set by Gpisetcp or default for presentation space). 
ulcodepage contains the current code page (0 indicates an error). 
hps contains the presentation space handle. You can retrieve the 
last error using WinGetLastError. These errors include: 


Ox207F PMERR INV HPS 
0x20F4 PMERR-PS BUSY 


The GpiQuerycurrentposition function returns the current position. 
fsuccess contains true if this function is successful. hps contains 
the presentation space handle. pptlpoint contains the current 
position. You can retrieve the last error using WinGetLastError. 
These errors include: 


Ox2060 PMERR INV DC TYPE 
0x207F PMERR-INV-HP5 
0x208C PMERR-INV-IN RETAIN MODE 
0x20F4 PMERR-PS BUSY 


The GpiQueryDefArcparams function returns the default arc 
parameters set by GpisetDefArcparams. fsuccess contains true if 
this function is successful. hps contains the presentation space 
handle. parcpArcparams contains the default arc parameters. You 
can retrieve the last error using WinGetLastError. These errors 
include: 


Ox207F PMERR INV HPS 
0x20F4 PMERR-PS BUSY 


The GpiQueryDefAttrs function returns the default attribute values 
for the specified primitive type. fsuccess contains true if this 
function is successful. hps contains the presentation space handle. 
IprimType contains the following primitive types: PRIM_LINE, 
PRIM_CHAR, PRIM_MARKER, PRIM_AREA, or PRIM_IMAGE. 
flAttrMask contains the attribute mask. Each flag that you set returns 
the corresponding attribute in ppbunAttrs. ppbunAttrs is a pointer 
to the attribute buffer. You can retrieve the last error using 
WinGetLastError. These errors include: 


Ox207F PMERR INV HPS 


Function 


fsuccess = 
GpiQueryDefault- 
ViewMatrix (hps, 
lcount, pmatlfArray) 


hps= 
GpiQueryDefchar- 
Box (hps, psizlsize) 


fsuccess = 
GpiQueryDefTag 
(hps, plTag) 


fsuccess 
G 


Description 


Ox20B9 PMERR INV PRIMITIVE TYPE 
0x20F4 PMERR-PS BUSY 
0x2109 PMERR-UN-SUPPORTED ATTR 


The GpiQueryDefaultviewMatrix returns the current default viewing 
transform. fsuccess contains true if this function is successful. hps 
contains the presentation space handle. ICount contains the number 
of elements in pmatlfArray. pmatlfArray contains the transform 
matrix. You can retrieve the last error using WinGetLastError. These 
errors include : 


Ox207F PMERR INV HPS 
0x2092 PMERR-INV-LENGTH OR COUNT 
0x20F4 PMERR-PS BUSY 


The GpiQueryDefcharBox function returns the current size of the 
default character box in world coordinates. fsuccess contains true if 
this function is successful. hps contains the presentation space 
handle. psizlsize contains the default character box size. You can 
retrieve the last error using WinGetLastError. These errors include: 


Ox207F PMERR INV HPS 
0x208C PMERR-INV-IN RETAIN MODE 
0x20F4 PMERR-PS BUSY 


The GpiQueryDefTag function returns the default value of the tag 
identifier. fsuccess contains true if this function is successful. hps 
contains the presentation space handle. plTag contains the default 
tag identifier. You can retrieve the last error using WinGetLastError. 
These errors include: 


Ox207F PMERR INV HPS 
0x20AI PMERR-INV-MICROPS FUNCTION 
0x20F4 PMERR-PS BUSY 


The GpiQueryDefviewingLimits function returns the default value of 


QueryDefviewing- the viewing limits. fsuccess contains true if this function is 


(hps 
mits) 


hdc= 
GpiQueryDevice 
(hps) 


successful. hps contains the presentation space handle. prclLimits 
contains the default viewing limits. You can retrieve the last error 
using WinGetLastError. These errors include: 


Ox207F PMERR INV HPS 
0x20F4 PMERR-PS BUSY 


The GpiQueryDevice function returns the handle of a currently 
associated device. hdc contains the device context handle, 0 to 
signify an error condition, or NULLHANDLE if no device context is 
associated. hps contains the presentation space handle. You can 
retrieve the last error using WinGetLastError. These errors include: 


Ox207F PMERR INV HPS 
0x20F4 PMERR-PS BUSY 


Table 3-42 Continued 


Function 


fsuccess = 
GpiQueryDevice- 
BitmapFormats (hps, 
lcount, alArray) 


Ivalue = 
GpiQuer 
Control 
lcontro 


[Mode - 
GpiQueryDrawing- 
Mode (hps) 


GpiQueryEditMode 


Description 


The GpiQueryDeviceBitmapFormats function returns the formats of 
the bitmaps supported internally by a device driver. fsuccess 
contains true if this function is successful. hps contains the 
presentation space handle. ICount contains the number of elements 
in aIArray. alArray contains the format data in pairs of cplanes, 
cBitcount elements. You can retrieve the last error using 
WinGetLastError. These errors include: 


Ox207F PMERR INV HPS 
0x2092 PMERR-INV-LENGTH OR COUNT 
0x20F4 PMERR-PS BUSY 


The GpiQueryDrawcontrol function returns the draw control set by 
GpisetDrawcontrol. Ivalue contains the value of the control and 
error indicators. hps contains the presentation space handle. 
IControl contains one of the following control types: DCTL_ERASE, 
DCTL_DISPLAY, DCTL_BOUNDARY, DCTL_DYNAMIC, or 
DCTL_CORRELATE. GpiQuerycolor returns one of the following 
values: 
-0001 DCTL ERROR 
0000 DCTL-OFF 
0001 DCTL-ON 


You can retrieve the last error using WinGetLastError. These errors 
include: 


Ox2063 PMERR INV DRAW CONTROL 
0x207F PMERR-INV-HPS 
0x20A0 PMERR-INV-MICROPS DRAW CONTROL 
0x20F4 PMERR-PS BUSY 


The GpiQueryDrawingMode function returns the current drawing 
mode. IMode contains the current drawing mode or 0 to signify an 
error condition. hps contains the presentation space handle. You 
can retrieve the last error using WinGetLastError. These errors 
include: 


Ox207F PMERR INV HPS 
0x20AI PMERR-INV-MICROPS FUNCTION 
0x20F4 PMERR-PS BUSY 


The GpiQueryEditMode function returns the current editing mode. 
IMode contains the current drawing mode or 0 to signify an error 
condition. hps contains the presentation space handle. 
GpiQueryEditMode returns one of the following values: 


0000 SEGEM ERROR 
0001 SEGEM-INSERT 
0002 SEGEM-REPLACE 


Function 


lRetLength = 
GpiQueryElement 
(hps, loft, 
lMaxLength, pbData) 


lElement = 
GpiQueryElement- 
Pointer (hps) 


IBeqLength = 
GpiQueryElement- 
Type (hps, plType, 
lLength, pszData) 


Description 


You can retrieve the last error using WinGetLastError. These errors 
include: 


Ox207F PMERR INV HPS 
0x20AI PMERR-INV-MICROPS FUNCTION 
0x20F4 PMERR-PS BUSY 


The GpiQueryElement function returns element content data. This is 
for the element currently pointed at by the element pointer. 
IBetLength contains the number of bytes returns (-1 indicates an 
error). hps contains the presentation space handle. loft contains the 
starting byte offset within the element. IMaxLength contains the size 
of pbData. pbData contains the element content data. You can 
retrieve the last error using WinGetLastError. These errors include: 


Ox206A 
0x207F 
0x2089 
0x2092 
0x20A1 
0x20E2 
0x20E5 
0x20E6 
0x20F4 


PMERR INV ELEMENT OFFSET 
PMERR-INV-HPS 
PMERR-INV-IN ELEMENT 
PMERR-INV-LE-NGTH OR COUNT 
PMERR-INV-MICROP5 FU-NCTION 
PMERR-NOT IN RETAIN MODE 
PMERR-NO €UERENT E-LEMENT 
PMERR-NO-CURRENT-SEG 
PMERR-PS-BUSY 


The GpiQueryElementpointer function returns the current element 
pointer. IElement contains the current element pointer (-1 indicates 
an error). hps contains the presentation space handle. You can 
retrieve the last error using WinGetLastError. These errors include: 


Ox207F PMERR INV HPS 
0x20AI PMERR-INV-MICROPS FUNCTION 
Ox2OE2 pMERR=Nof IN RETAIN_MODE 
0x20E6 PMERR NO 5UERENT SEG 
0x20F4 PMERR-PS -BUSY 


The GpiQueryElementType function returns information about the 
element pointed to by the element pointer. IBeqLength contains the 
size of the buffer required to hold the element content (-1 indicates 
an error). hps contains the presentation space handle. plType 
contains the element type. ILength contains the size of pszData. 
pszData contains a description of the data buffer. You can retrieve 
the last error using WinGetLastError. These errors include: 


Ox207F 
0x2089 
0x2092 
0x20A1 
0x20E2 
0x20E5 
0x20E6 
0x20F4 


PMERR INV HPS 
PMERR-INV-IN ELEMENT 
PMERR-INV-LE-NGTH OR COUNT 
PMERR-INV-MICROP5 FU-NCTION 
PMERR-Not IN RETAIN MODE 
PMERR-NO euERENT E-LEMENT 
PMERR-NO-CURRENT-SEG 
PMERR-PS-BUSY 


Table 3 -42 Continued 


Function 


cbBetLength = 
GpiQueryFacestring 
(hps, pszFamily 
Name, pfndFace 
Attrs, lLength, 
pszcompoundFace 
Name) 


flActions = 
GpiQueryFontAction 
(hab, floptions) 


lRemFonts = 
GpiQueryFontFile- 
Descriptions (hab, 
pszFilename, 
plcount, 
affdescsNames) 


fsuccess = 
GpiQueryFontMetrics 
(hps, lMetricsLength, 
pfmMetrics) 


Description 


The GpiQueryFacestring returns a compound face name for a font. 
cbBetLength contains the length of the compound face name (0 
indicates an error). hps contains the presentation space handle. 
pszFamilyName contains the family. pfndFaceAttrs contains the 
face name description (a set of font characteristics). ILength contains 
the size of pszcompoundFaceName. pszcompoundFaceName 
contains the generated compound face name for the font. You can 
retrieve the last error using WinGetLastError. These errors include: 


Ox201D PMERR INV FACENAME 
0x202F PMERR-EON-T NOT LOADED 
0x207F PMERR-INV H-PS 
0x20F4 PMERR-PS BUSY 
0x2115 PMERR -INV-FACENAMEDESC 


The GpiQueryFontAction function determines if the available fonts 
have changed since the last time you called the function. flActions 
contains the actions and error indicators. hab contains the anchor 
block handle. floptions contains one or more of the following 
options : QFA_PUBLIC and QFA_PRIVATE. GpiQueryFontAction 
returns one of the following values: 


-0001 QFA_ERROR 
0001 QFA_PUBLIC 
0002 QFA_PRIVATE 


You can retrieve the last error using WinGetLastError. These errors 
include: 


Ox20A9 PMERR INV OR INCOMPAT OPTIONS 


The GpiQueryFontFileDescriptions function determines whether a 
file is a font resource file. If so, it returns the family and face names 
for the fonts that it contains. IBemFonts contains the number of 
fonts that affdescsNames could not hold (-1 indicates an error). 
hab contains the anchor block handle. pszFilename contains the 
font file name. plcount contains the number of family and face 
names that you want returned. affdescsNames is an array of file 
descriptors. Each field is 32-bytes long. You can retrieve the last 
error using WinGetLastError. These errors include: 


Ox2073 PMERR INV FONT FILE DATA 
0x2092 PMERR-INV-LENGTH O-R COUNT 


The GpiQueryFontMetrics function returns a record containing the 
font metrics (in world coordinates) for the currently selected logical 
font. fsuccess contains true if this function is successful. hps 
contains the presentation space handle. IMetricsLength contains 
the size of pfmMetrics. pfmMetrics contains the font metrics for the 


Function 


lBemFonts = 
GpiQueryFonts (hps, 
floptions, 
pszFacename, 
plBeqFonts, 
lMetricsLength, 
afmMetrics) 


lRemFonts = 
GpiQueryFullFont- 
FileDescs (hab, 
pszFilename, 
plcount, pNames, 


Description 


currently selected logical font. You can retrieve the last error using 
WinGetLastError. These errors include: 


Ox2014 PMERR COORDINATE_OVERFLOW 
0x207F PMERR-INV HPS 
0x2092 PMERR-INV-LENGTH OR_COUNT 
0x20F4 PMERR-PS BUSY 


The GpiQueryFonts function returns a record that provides details 
for the fonts that match pszFacename. IBemFonts contains the 
number of fonts that affdescsNames could not hold (-1 indicates 
an error). hps contains the presentation space handle. floptions 
contains the flags that control which fonts get listed. This includes: 
QF_PUBLIC, QF_PRIVATE, QF_NO_DEVICE, and 
QF_NOGENERIC. pszFacename contains the font face name. A 
null handle forces OS/2 for query all fonts. plBeqFonts contains 
the number of fonts that you want queried; it returns the actual 
number of fonts queried. IMetricsLength contains the size of 
pfmMetrics. afmMetrics is an array that contains the font metrics 
for the queried fonts. You can retrieve the last error using 
WinGetLastError. These errors include: 


Ox2014 PMERR COORDINATE OVERFLOW 
0x207F PMERR-INV HPS 
0x2092 PMERR-INV-LENGTH OR COUNT 
0x20F4 PMERR-PS BUSY 


The GpiQueryFullFontFileDescs function determines whether a file 
is a font resource file. If so, it returns the family and face names for 
the fonts that it contains. IBemFonts contains the number of fonts 
that affdescsNames could not hold (-1 indicates an error). hab 
contains the anchor block handle. pszFilename contains the font 


blNamesBuffLength) file name. plcount contains the number of family and face names 


that you want returned. pNames is a buffer containing the font file 
descriptors. Each entry contains one font file family and face name 
pair. plNamesBuffLength contains the size of pNames. You can 
retrieve the last error using WinGetLastError. These errors include: 


Ox2073 PMERR INV FONT FILE DATA 
0x2092 PMERR-INV-LENGTH O-R COUNT 


The GpiQueryGraphicsField function returns the bottom-left and 
top-right corners of the graphics field (in presentation page units). 
fsuccess contains true if this function is successful. hps contains 
the presentation space handle. prclField contains the graphics field 
coordinates. You can retrieve the last error using WinGetLastError. 
These errors include: 


Ox207F PMERR INV HPS 
0x20F4 PMERR-PS BUSY 


The GpiQuerylnitialsegmentAttrs function returns the current value 


fsuccess = 
GpiQueryGraphics 
Field (hps, prclField) 


lvalue = 
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Function 


GpiQuerylnitial- 
SegmentAttrs (hps, 
lAttribute) 


lF3eturned = 
GpiQueryKerning- 
Pairs (hps, lcount, 
akrnprData) 


lLineEnd = 
GpiQueryLineEnd 
(hps) 


lLineJoin = 
GpiQueryLineJoin 
(hps) 


Description 


of a particular initial segment attribute. Ivalue contains the segment 
attribute value or error indicator. hps contains the presentation 
space handle. IAttribute contains the attribute you want to query. 
These attributes include: AITR_DETECTABLE, AITR_VISIBLE, 
AITR_CHAINED , ATTR_DYNAMIC , AITR_FASTCHAIN , 
ATTR_PROP_DETECTABLE , and AITR_PROP_VISIBLE. 
GpiQuerylnitialsegmentAttrs returns one of the following values: 
-0001 AITR ERROR 
OOOO ATrR-OFF 
0001 AITR-ON 


You can retrieve the last error using WinGetLastError. These errors 
include: 


Ox207F PMERR INV HPS 
0x20AI PMERR-INV-MICROPS FUNCTION 
0x20C5 PMERR-INV-SEG ATTk 
Ox20F4 PMERR-PS BUSY- 
The GpiQueryKerningpairs function returns the kerning pair 
information for the logical font identified by the current value of the 
character set attribute. IBeturned contains the number of kerning 
pairs returned or an error indicator (a value of -1). hps contains the 
presentation space handle. ICount contains the number of elements 
in akrnprData. akrnprData is an array that contains the kerning 
pairs. You can retrieve the last error using WinGetLastError. These 
errors include: 


Ox2014 PMERR COORDINATE OVERFLOW 
0x207F PMERR-INV HPS 
0x2092 PMERR-INV-LENGTH OR COUNT 
0x20F4 PMERR~PS BUSY 


The GpiQueryLineEnd function returns the current line-end 
attribute. ILineEnd contains the line end attribute, 
LINEEND_DEFAULT, or an error indicator (a value of -1). hps 
contains the presentation space handle. You can retrieve the last 
error using WinGetLastError. These errors include: 


Ox2060 PMERR INV DC TYPE 
0x207F PMERR-INV-HP§ 
Ox208C PMERR-INV-IN RETAIN MODE 
0x20F4 PMERR-PS BUSY 


The GpiQueryLineJoin function returns the current line-join 
attribute. ILineJoin contains the line join attribute, 
LINEJOIN_DEFAULT, or an error indicator (a value of -1). hps 
contains the presentation space handle. You can retrieve the last 
error using WinGetLastError. These errors include: 


Function 


lLineType = 
GpiQueryLineType 
(hps) 


lLinewidth = 
GpiQueryLinewidth 
(hps) 


ILinewidth = 
GpiQueryLinewidth- 
Geom (hps) 


lF3etcount = 
GpiQueryLogcolor- 
Table (hps, 
floptions, lstart, 
ICount, alArray) 


Description 


Ox2060 PMERR INV DC TYPE 
0x207F PMERR-INV-HP5 
0x208C PMERR-INV-IN RETAIN MODE 
0x20F4 PMERR-PS BUSY 


The GpiQueryLineType function returns the current line-type 
attribute. ILineType contains the line type attribute, 
LINETYPE_DEFAULT, or an error indicator (a value of -1). hps 
contains the presentation space handle. You can retrieve the last 
error using WinGetLastError. These errors include: 


Ox2060 PMERR INV DC TYPE 
0x207F PMERR-INV-HP5 
0x208C PMERR-INV-IN RETAIN MODE 
0x20F4 PMERR-PS BUSY 


The GpiQueryLinewidth function returns the current cosmetic 
line-width attribute. ILinewidth contains the line width attribute, 
LINEWIDTH_DEFAULT, or an error indicator (a value of -1). hps 
contains the presentation space handle. You can retrieve the last 
error using WinGetLastError. These errors include: 


Ox2060 PMERR INV DC TYPE 
0x207F PMERR-INV-HP§ 
Ox208C PMERR-INV-IN RETAIN MODE 
0x20F4 PMERR-PS BUSY 


The GpiQueryLinewidthGeom function returns the current 
geometric line-width attribute. ILinewidth contains the line width 
attribute or an error indicator (a value of -1). hps contains the 
presentation space handle. You can retrieve the last error using 
WinGetLastError. These errors include: 


Ox2060 PMERR INV DC TYPE 
0x207F PMERR-INV-HP5 
0x208C PMERR-INV-IN RETAIN MODE 
0x20F4 PMERR-PS BUSY 


The GpiQueryLogcolorTable function returns the logical color table. 
IBetcount contains the number of returned elements and error 
indicators. hps contains the presentation space handle. floptions 
contains the option values including: LCOLOPT_INDEX. Istart 
contains the starting index. ICount contains the number of elements 
in alArray. alArray contains the returned color table. If the 
LCOLOPT_INDEX flag is not set, then alArray contains an array of 
RGB values. It is set, then alArray contains alternating color indexes 
and RGB values. GpiQueryLogcolorTable returns one of the 
following values: 
-0002 QLCT_RGB 
-0001 QLCT_ERROR 
>0 Number of returned elements 
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Function 


fsuccess = 
GpiQueryLogical- 
Font (hps, lLcid, 
pName, pfatAttrs, 
lAttrsLength) 


lsymbol = 
GpiQueryMarker 
(hps) 


fsuccess = 
GpiQueryMarkerBox 
(hps, psizfxsize) 


Description 


You can retrieve the last error using WinGetLastError. These errors 
include: 


Ox2057 
0x2058 
0x207F 
0x2092 
0x20F4 
0x210F 


PMERR INV COLOR OPTIONS 
PMERR-INV-COLOR-START INDEX 
PMERR-INV-HPS 
PMERR-INV-LENGTH OR COUNT 
PMERR-PS BUSY 
PMERR-PALETTE SELECTED 


The GpiQueryLogicalFontFunction returns a description of a logical 
font. fsuccess contains true if this function is successful. hps 
contains the presentation space handle. ILcid contains the local font 
identifier in the range from 0 (default) to 254. pName contains an 
8-character logical font name. pfatAttrs contains the font attributes. 
IAttrsLength contains the length of the pfatAttrs buffer. You can 
retrieve the last error using WinGetLastError. These errors include: 


Ox207F PMERR INV HPS 
0x2092 PMERR-INV-LENGTH OR COUNT 
0x20CA PMERR-INV-SETID 
0x20F4 PMERR-PS BUSY 
0x2102 PMERR-SETID IN USE 


The GpiQueryMarker function returns the current value of the 
marker symbol attribute (set by the GpisetMarker function). Isymbol 
contains the marker symbol value and error indicators. hps contains 
the presentation space handle. GpiQueryMarker returns one of the 
following values : 
-0001 MARKSYM ERROR 
0000 MARKSYM-DEFAULT 
>0 Marker symbol 


You can retrieve the last error using WinGetLastError. These errors 
include: 


Ox2060 PMERR INV DC TYPE 
0x207F PMERR-INV-HP5 
0x208C PMERR-INV-IN RETAIN MODE 
0x20F4 PMERR-PS BUSY 


The GpiQueryMarkerBox function returns the current value of the 
marker-box attribute (set by the GpisetMarkerBox function). 
fsuccess contains true if this function is successful. hps contains 
the presentation space handle. psizlfxsize contains the size of the 
marker box in world coordinates. You can retrieve the last error 
using WinGetLastError. These errors include: 


Ox2060 PMERR INV DC TYPE 


Function 


Iset = 
GpiQueryMarkerset 
(hps) 


fsuccess = 
GpiQueryMetaFile- 
Bits (hmf, loffset, 
lLength, pbData) 


lLength = 
GpiQueryMetaFile- 
Length (hmf) 


lMixMode = 
GpiQueryMix (hps) 


Description 


Ox207F PMERR INV HPS 
0x208C PMERR-INV-IN RETAIN MODE 
0x20F4 PMERR-PS BUSY 


The GpiQueryMarkerset function returns the current value of the 
marker-set attribute (set by the GpisetMarkerset function). Iset 
contains the marker set value and error indicators. hps contains the 
presentation space handle. GpiQueryMarker returns one of the 
following values: 
-0001 LCID ERROR 
0000 LCID-DEFAULT 
>0 Markgi set local identifier 


You can retrieve the last error using WinGetLastError. These errors 
include: 


Ox2060 PMERR INV DC TYPE 
0x207F PMERR-INV-HP5 
0x208C PMERR-INV-IN RETAIN MODE 
0x20F4 PMERR-PS BUSY 


The GpiQueryMetaFileBits function stores a metafile to application 
storage. fsuccess contains true if this function is successful. hmf 
contains the metafile handle. Ioffset contains the offset within the 
metafile where you want to start the data transfer. ILength contains 
the amount of metafile data to copy in bytes. pbData is a pointer to 
the metafile data storage area. You can retrieve the last error using 
WinGetLastError. These errors include : 


Ox207E PMERR INV HMF 
0x209E PMERR-INV-MEIAFILE LENGTH 
0x209F PMERR-INV-METAFILE-OFFSET 
0x20D9 PMERR-METAFILE IN 0SE 
0x2106 PMERR-TOO MAN-Y ivlETAFILES IN USE 


The GpiQueryMetaFileLength function returns the length of a 
memory metafile in bytes. ILength contains the total length of the 
metafile in bytes (-1 indicates an error). hmf contains the metafile 
handle. You can retrieve the last error using WinGetLastError. These 
errors include: 


Ox207E PMERR INV HMF 
0x2106 PMERR-TOO MANY METAFILES IN USE 


The GpiQueryMix function returns the current value of the character 
foreground color mixing mode (set by the GpisetMix function). 
IMixMode contains the foreground color mixing mode and error 
indicators. hps contains the presentation space handle. 
GpiQueryMix returns one of the following values: 
-0001 FM ERROR 
0000 FM-DEFAULT 
> 0 Mix-mode 
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peREREENRE 


Function 


fsuccess = 
GpiQueryModel- 
TransformMatrix 
(hps, lcount, 
pmatlfArray) 


lF]bgout - 
GpiQueryNearest- 
Color (hps, 
uloptions, lBgbln) 


lcount - 
GpiQueryNumber- 
Setlds (hps) 


fsuccess = 
GpiQuerypage- 
Viewport (hps, 
prclviewport) 


Description 


You can retrieve the last error using WinGetLastError. These errors 
include: 


Ox2060 PMERR INV DC TYPE 
0x207F PMERR-INV-HP5 
0x208C PMERR-INV-IN RETAIN MODE 
0x20F4 PMERR-PS BUSY 


The GpiQueryModelTransformMatrix function returns the current 
model transform. fsuccess contains true if this function is 
successful. hps contains the presentation space handle. ICount 
contains the number of elements in pmatlfArray. pmatlfArray 
contains the transform matrix. You can retrieve the last error using 
WinGetLastError. These errors include : 


Ox2060 PMERR INV DC TYPE 
0x207F PMERR-INV-HP5 
0x208C PMERR-INV-IN RETAIN MODE 
0x2092 PMERR-INV-LE-NGTH O-R COUNT 
0x20F4 PMERR-PS BUSY 


The GpiQueryNearestcolor function returns the color on the current 
devices that most closely matches the specified color (both colors use 
RGB terms). This function returns a pure color, it does not take 
dithered colors into account. IBgbout contains the color that most 
closely matches the specified color (-1 indicates an error). hps 
contains the presentation space handle. uloptions is a reserved 
parameter, set it to zero. IBgbln contains the required color. You 
can retrieve the last error using WinGetLastError. These errors 
include: 


Ox2057 PMERR INV COLOR OPTIONS 
0x207F PMERR-INV-HPS 
0x20C3 PMERR-INV-RGBCOLOR 
0x20F4 PMERR-PS BUSY 


The GpiQueryNumbersetlds function returns the number of local 
identifiers (lcids) that refer to fonts or bitmaps currently in use. 
ICount contains the number of lcids (-1 indicates an error). hps 
contains the presentation space handle. You can retrieve the last 
error using WinGetLastError. These errors include: 


Ox207F PMERR INV HPS 
0x20F4 PMERR-PS BUSY 


The GpiQueryviewport function returns the current viewport. 
fsuccess contains true if this function is successful. hps contains 
the presentation space handle. prclviewport contains the size and 
position of the page viewport in device units. You can retrieve the 
last error using WinGetLastError. These errors include: 


Function 


hpal = 
GpiQuerypalette 
(hps) 


lF3etcount = 
GpiQuerypalettelnfo 
(hpal, hps, floptions, 
lstart, lcount, 
alArray) 


lpatternsymbol = 
GpiQuerypattern 
(hps) 


Description 


Ox2060 PMERR INV DC TYPE 
0x207F PMERR-INV-HP§ 
Ox208C PMERR-INV-IN RETAIN MODE 
0x20F4 PMERR-PS BUSY 


The GpiQuerypalette function returns the handle of the palette 
currently selected into a presentation space. hpal contains the 
palette handle, a NULLHANDLE if no palette is selected, or -1 to 
indicate an error. hps contains the presentation space handle. You 
can retrieve the last error using WinGetLastError. These errors 
include: 


Ox207F PMERR INV HPS 
0x20F4 PMERR-PS BUSY 


The GpiQuerypalettelnfo function returns the specified palette's 
information. It uses the same information required to create a 
palette using Gpicreatepalette. IBetcount contains the number of 
returned elements (-1 to indicate an error). hpal contains the palette 
handle. Passing a null handle in this parameter returns the 
information for the currently selected presentation space palette. 
hps contains the presentation space handle. floptions contains the 
option values including: LCOLOPT_INDEX. Istart contains the 
starting index. ICount contains the number of elements in alArray. 
alArray contains the returned color table. If the LCOLOPT_INDEX 
flag is not set, then alArray contains an array of RGB values. If it is 
set, then alArray contains alternating color indexes and RGB values. 
You can retrieve the last error using WinGetLastError. These errors 
include: 


Ox2057 
0x2058 
0x207F 
0x2092 
0x20F4 
0x2 1 1 1 
0x2112 


PMERR INV COLOR OPTIONS 
PMERR-INV-COLOR-START INDEX 
PMERR-INV-HPS 
PMERR-INV-LENGTH OR COUNT 
PMERR-PS BUSY 
PMERR-INV HPAL 
PMERR-PAL-BITE BUSY 


The GpiQuerypattern function returns the current value of the 
shading-pattern symbol (set by the Gpisetpattern function). 
Ipatternsymbol contains the pattern symbol and error indicators. 
hps contains the presentation space handle. GpiQuerypattern 
returns one of the following values: 
-0001 PATSYM ERROR 
0000 PATSYM-DEFAULT 
>0 Pattern symbol 


You can retrieve the last error using WinGetLastError. These errors 
include: 


Ox2060 PMERR INV DC TYPE 
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Function 


fsuccess = 
GpiQuerypatternBef- 
Point (hps, 
pptlBefpoint) 


lset = 
GpiQuerypatternset 
(hps) 


lcolor = 
GpiQuerypel (hps, 
pptlpoint) 


Description 


Ox207F PMERR INV HPS 
0x208C PMERR-INV-IN RETAIN MODE 
0x20F4 PMERR-PS BUSY 


The GpiQuerypatternRefpoint function returns the current pattern 
reference point (set by the GpisetpatternRefpoint function). 
fsuccess contains true if this function is successful. hps contains 
the presentation space handle. pptlBefpoint contains the pattern 
reference point (default is 0, 0). You can retrieve the last error using 
WinGetLastError. These errors include : 


Ox2060 PMERR INV DC TYPE 
0x207F PMERR-INV-HP§ 
Ox208C PMERR-INV-IN RETAIN MODE 
0x20F4 PMERR-PS BUSY 


The GpiQuerypatternset function returns the current value of the 
pattern-set identifier (set by the Gpisetpatternset function). Iset 
contains the pattern set local identifier and error indicators. hps 
contains the presentation space handle. GpiQuerypatternset returns 
one of the following values: 
-0001 LCID ERROR 
0000 LCID-DEFAULT 
>0 Patter-n symbol 


You can retrieve the last error using WinGetLastError. These errors 
include: 


Ox2060 PMERR INV DC TYPE 
0x207F PMERR-INV-HP5 
0x208C PMERR-INV-IN RETAIN MODE 
0x20F4 PMERR-PS BUSY 


The GpiQuerypal function returns the color of a pel (as an RGB 
value) at a position specified in world coordinates. IColor returns the 
color index of the pel, CLR_NOINDEX, or -1 to indicate an error. . 
hps contains the presentation space handle. pptlpoint contains the 
pel position in world coordinates. You cannot specify a point outside 
any of the current clipping objects. You can retrieve the last error 
using WinGetLastError. These errors include: 


Ox205B 
0x2060 
0x207F 
0x20E4 
0x20EF 
0x20F0 
0x20F4 


PMERR INV COORDINATE 
PMERR-INv-Dc rmE 
PMERR-INV-HP5 
PMERR-NO -BITMAP SELECTED 
PMERR-PEL- IS CLIPPED 
PMERR-PEL-NOT AVAIIABLE 
PMERR-PS BUSY 


Function 


fsuccess = 
GpiQuerypick- 
Apertureposition 
(hps, pptlpoint) 


fsuccess = 
GpiQuerypick- 
Aperturesize (hps, 
psizlsize) 


loptions = 
GpiQueryps (hps, 
psizlsize) 


lpetcount = 
GpiQueryBealcolors 
(hps, uloptions, 
lstart, lcount, 
alcolors) 


lcomplexity = 
GpiQueryBegionBox 


Description 


The GpiQuerypickApertureposition function returns the center of 
the pick aperture. fsuccess contains true if this function is 
successful. hps contains the presentation space handle. pptlpoint 
contains the pick aperture center point. You can retrieve the last 
error using WinGetLastError. These errors include: 


Ox2060 PMERR INV DC TYPE 
0x207F PMERR-INV-HP§ 
Ox20F4 PMERR-PS BUSY 


The GpiQuerypickAperturesize function returns the current size of 
the pick aperture (set by the GpisetpickAperture function). 
fsuccess contains true if this function is successful. hps contains 
the presentation space handle. psizlsize contains the pick aperture 
size in presentation page coordinates. You can retrieve the last error 
using WinGetLastError. These errors include: 


Ox2060 PMERR INV DC TYPE 
0x207F PMERR-INV-HP5 
0x20F4 PMERR-PS BUSY 


The GpiQueryps function returns the page parameters for the 
presentation space. IOptions contains the presentation space 
options. This includes the following fields: PS_UNITS, 
PS_FORMAT, PS_TYPE, and PS_MODE. hps contains the 
presentation space handle. psizlsize contains the presentation-page 
size. You can retrieve the last error using WinGetLastError. These 
errors include: 


Ox207F PMERR INV HPS 
0x20F4 PMERR-PS BUSY 


The GpiQueryRealcolors function returns the RGP values of the 
distinct colors available on the currently associated device. 
Ipetcount contains the number of returned elements (-1 to indicate 
an error). hps contains the presentation space handle. uloptions 
contains the option values including: LCOLOPT_INDEX. Istart 
contains the starting color number. ICount contains the number of 
elements in alcolors. alcolors contains the returned color table. If 
the LCOLOPT_INDEX flag is not set, then alArray contains an 
array of RGB values. If it is set, then alArray contains alternating 
color indexes and RGB values. You can retrieve the last error using 
WinGetLastError. These errors include: 


Ox2057 PMERR INV COLOR OPTIONS 
0x2058 PMERR-INV-COLOR-START INDEX 
0x207F PMERR-INV-HPS 
0x2092 PMERR-INV-LENGTH OR COUNT 
0x20F4 PMERR-PS BUSY 


The GpiQueryRegionBox returns the dimensions of the smallest 
rectangle able to bound the region. IComplexity contains the 
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Function 


(hps, hrgn, 
prclBound) 


fsuccess = 
GpiQueryBegion- 
Bects (hps, hrgn, 
prclBound, 
prgnrccontrol, 
arclBects) 


IRgbcolor= 
GpiQueryBGBColor 
(hps, FIOptions, 
lcolorlndex) 


Description 


complexity of the resulting region or an error indicator. hps contains 
a presentation space handle. hrgn contains the region handle. 
ppclBound contains the bounding rectangle dimensions in world 
coordinates. GpiQueryRegionBox returns one of the following values: 
0000 RGN ERROR 
0001 RGN-NULL 
0002 RGN-RECT 
0003 RGN-COMPLEX 
You can retrieve the last error using WinGetLastError. These errors 
include: 
Ox2034 PMERR HRGN BUSY 
0x207F PMERR-INV His 
0x2080 PMERR-INV-HRGN 
0x20F4 PMERR-PS BUSY 
Ox2OF8 PMERR-REaloN Is cLlp REGION 
The GpiQueryRegionRects r=tu=ns th; rectangles used to define the 
specified region. fsuccess contains true if this function is successful. 
hps contains the presentation space handle. hrgn contains the 
region handle. ppclBound contains the bounding rectangle 
dimensions in world coordinates. A value of NULL returns all the 
rectangles in the region. prgnrccontrol contains the processing 
control structure. arclBects contains an array of rectangle 
structures. You can retrieve the last error using WinGetlrdstError. 
These errors include: 
Ox2034 PMERR HRGN BUSY 
0x205B PMERR-INV COORDINATE 
0x207F PMERR-INV-HPS 
0x2080 PMERR-INV-HRGN 
0x20BD PMERR-INV-RECT 
0x20BE PMERR-INV-HRGN CONTROL 
0x20F4 PMERR-PS BUSY 
0x20F8 PMERR-REGION IS CLIP REGION 
The GpiQueryRG5Color fun-cti;n retu-ms the actual RGB color 
residing at a particular index on the currently-associated device. (If 
you load an RGB logical color table, then this function returns the 
same value as the GpiQueryNearestcolor function.) I Bgbcolor 
contains the RGB color providing the closest match to the specified 
color index (-1 indicates an error). hps contains the presentation, 
space handle. floptions contains the option values including: 
LCOLOPT_INDEX. I start contains the starting color number. 
IColorlndex contains any normally valid color index value except 
CLR_DEFAULT. You can retrieve the last error using 
WinGetLastError. These errors include : 
Ox2056 PMERR INV COLOR INDEX 


Function 


lvalue = 
GpiQuerysegment- 
Attrs (hps, lsegid, 
lAttribute) 


lF3etcount = 
GpiQuerysegment- 
Names (hps, 
lFirstsegid, 
lLastsegid, lMax, 
alsegids) 


lsegid = 
GpiQuerysegment- 
Priority (hps, 
lBefsegid, lorder) 


Description 


Ox2057 PMERR INV COLOR OPTIONS 
0x207F PMERR-INV-HPS 
0x20F4 PMERR-PS BUSY 
The GpiQuerysegmentAttrs function returns the current value of the 
specified attribute (set by the GpisetsegmentAttrs function). Ivalue 
contains the segment attribute value or error indicator. hps contains 
the presentation space handle. Isegid contains the segment 
identifier. IAttribute contains the attribute you want to query. These 
attributes include: AITR_DETECTABLE, AITR_VISIBLE, 
AITR_CHAINED , AITR_DYNAMIC , AITR_FASTCHAIN , 
AITR_PROP_DETECTABLE , and AITR_PROP_VISIBLE. 
GpiQuerysegmentAttrs returns one of the following values: 
-0001 AITR ERROR 
0000 AITR-OFF 
0001 ATTR-ON 
You can retrieve the last error using WinGetLastError. These errors 
include: 
Ox207F 
0x20A1 
0x20C5 
0x20C8 
0x20F4 
0x2100 


PMERR INV HPS 
PMERR-INV-MICROPS FUNCTION 
PMERR-INV-SEG AITE 
PMERR-INV-SEG-NAME 
PMERR-PS BUSY- 
PMERR-SE6 NOT FOUND 


The GpiQuerysegmentNames function returns the identifiers of all 
segments that exist with identifiers in a specified range. (This 
function does not return nonretained segments.) lBetcount contains 
the number of returned elements (-1 to indicate an error). hps 
contains the presentation space handle. IFirstseg and lLastseg 
contain the identifiers of the first and last segments that you want to 
query. IMax contains the number of segment identifiers that you 
want returned in alsegids. alsegids is an array containing the 
required segment identifiers. You can retrieve the last error using 
WinGetLastError. These errors include : 
Ox207F PMERR INV HPS 
0x2092 PMERR-INV-LENGTH OR COUNT 
0x20AI PMERR-INV-MICROPS FU-NCTION 
0x20C8 PMERR-INV-SEG NAM-E 
0x20F4 PMERR-PS BUSY- 
The GpiQuerysegmentpriority function returns the identifier of the 
segment chained immediately before (lower priority) or after (higher 
priority) a specified reference segment. Isegid contains the segment 
identifier: 0 when the segment is either the highest (lorder = 
HIGHER_PRI) or lowest (lorder = LOWER_PRI) priority segment, 
or -1 to indicate an error. hps contains the presentation space 
handle. IBefsegid contains the reference segment identifier. Iorder 
contains a flag that shows whether you want a lower (LOWER_PRI) 
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Function 


fsuccess = 
GpiQuerysegment- 
TransformMatrix 
(hps, lsegid, lcount, 
pmatlfArray) 


fsuccess = 
GpiQuerysetlds 
(hps, lcount, 
alTypes, aNames, 
allcids) 


lvalue = 
GpiQuerystopDraw 
(hps) 


Description 


or higher (HIGHER_PRI) priority segment. You can retrieve the last 
error using WinGetLastError. These errors include: 
Ox207F PMERR INV HPS 
0x20AI PMERR-IIV-MICROPS FUNCTION 
0x20AB PMERR-INV-ORDERING PARM 
0x20C8 PMERR-INV-SEG NAME- 
Ox20F4 PMERR-PS BUSY- 
Ox2OFF PMERR-sEa NOT CHAINED 
0x2100 PMERR -SEG -NOT-FOUND 
The GpiQuerysegmentT-ransfo-rmMatrix function returns the 
elements of the transform of the specified segment. fsuccess 
contains true if this function is successful. hps contains the 
presentation space handle. Isegid contains the segment identifier. 
ICount contains the number of elements in pmatlfArray. 
pmatlfArray contains the transform matrix. You can retrieve the last 
error using WinGetLastError. These errors include: 
Ox207F PMERR INV HPS 
0x2092 PMERR-INV-LENGTH OR COUNT 
0x20AI PMERR-INV-MICROP5 FU-NCTION 
0x20C8 PMERR-INV-SEG NAM-E 
0x20F4 PMERR-PS BUSY- 
Ox2100 PMERR-SE6 NOT FOUND 
The GpiQuerysetlas fun-ction r-eturns information about all fonts 
created by the GpicreateLogFont function and tagged bitmaps. 
fsuccess contains true if this function is successful. hps contains 
the presentation space handle. ICount contains the number of items 
you want to query. alTypes contains a list of the object types that 
you want to retrieve. They include: LCIDT_FONT and 
LCIDT_BITMAP. aNames contains an array of 8-character font 
names. (Bitmaps set the array entry to zero.) allcids is an array of 
local identifiers. You can retrieve the last error using 
WinGetLastError. These errors include : 
Ox207F PMERR INV HPS 
0x2092 PMERR-INV-LENGTH OR COUNT 
0x20F4 PMERR-PS BUSY 
The GpiQuerystopDraw function returns the status of the ``stop 
draw" condition. Ivalue contains the stop draw condition or error 
indicator. hps contains the presentation space handle. 
GpiQuerystopDraw returns one of the following values: 
-0001 SDW ERROR 
0000 SDW-OFF 
0001 SDW-ON 
You can retrieve the last error using WinGetLastError. These errors 
include: 


Function 


fsuccess = 
GpiQueryTag (hps, 
plTag) 


fsuccess = 
GpiQueryText- 
Alignment (hps 
plHorizontal, 
plvertical) 


fsuccess = 
GpiQueryTextBox 
(hps, lcountl , 
pchstring, lcount2, 
aptlpoints) 


fsuccess = 
GpiQueryviewing- 
Limits (hps, 
prclLimits) 


Description 


Ox207F PMERR INV HPS 
0x20AI PMERR-INV-MICROPS FUNCTION 


The GpiQueryTag function returns the current value of the tag 
identifier (set by the GpisegTag function). fsuccess contains true if 
this function is successful. hps contains the presentation space 
handle. plTag contains the tag identifier. You can retrieve the last 
error using WinGetLastError. These errors include: 


Ox207F PMERR INV HPS 
0x20AI PMERR-INV-MICROPS FUNCTION 
0x20F4 PMERR-PS BUSY 


The GpiQueryTextAlignment function returns the current value of 
the text alignment attribute (set by the GpisetTextAlignment 
function). fsuccess contains true if this function is successful. hps 
contains the presentation space handle. plHorizontal contains the 
horizontal alignment value. plvertical contains the vertical alignment 
value. You can retrieve the last error using WinGetLastError. These 
errors include : 


Ox2060 PMERR INV DC TYPE 
0x207F PMERR-INV-HP§ 
Ox208C PMERR-INV-IN RETAIN MODE 
0x20F4 PMERR-PS BUSY 


The GpiQueryBox function returns the relative coordinates of the 
four corners of a text box. fsuccess contains true if this function is 
successful. hps contains the presentation space handle. ICountl 
contains the number of characters in pchstring. pchstring contains 
the character string. ICount2 contains the number of points that you 
want returned in aptlpoints. Using TXTBOX_COUNT returns the 
maximum amount of information. aptlpoints contains a list of 
points in world coordinates. You can retrieve the last error using 
WinGetLastError. These errors include : 


Ox2014 
0x2060 
0x207F 
0x208C 
0x2092 
0x20F4 


PMERR COORDINATE OVERFLOW 
PMERR-INv Dc rvpE- 
PMERR-INV-HP§ 
PMERR-INV-IN RETAIN MODE 
PMERR-Irv-LE-NGTH O-R cOuNT 
PMERR-PS BUSY 


The GpiQueryviewingLimits function returns the current value of 
the viewing limits (set by the GpisetviewingLimits function). 
fsuccess contains true if this function is successful. hps contains 
the presentation space handle. prclLimits contains the viewing 
limits. You can retrieve the last error using WinGetLastError. These 
errors include : 


Ox2060 PMERR INV DC TYPE 
0x207F PMERR-INV-HP§ 
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Function 


fsuccess = 
GpiQueryviewing- 
TransformMatrix 
(hps, lcount, 
pmatlfArray) 


fsuccess = 
GpiQuerywidthTable 
(hps, lFirstchar, 
lcount, alData) 


llnside = 
GpiBectlnBegion 
(hps, hrgn, prclBect) 


Description 


Ox208C PMERR INV IN RETAIN MODE 
0x20F4 PMERR-PS BUSY 


The GpiQueryviewingTransformMatrix function returns the current 
viewing transform. fsuccess contains true if this function is 
successful. hps contains the presentation space handle. ICount 
contains the number of elements in pmatlfArray. pmatlfArray 
contains the transform matrix. You can retrieve the last error using 
WinGetLastError. These errors include: 


Ox207F PMERR INV HPS 
0x2092 PMERR-INV-LENGTH OR COUNT 
0x20AI PMERR-INV-MICROPS FU-NCTION 
0x20F4 PMERR-PS BUSY 


The GpiQuerywidthTable returns the width table information for the 
logical font identified by the value of the character-set attribute. 
fsuccess contains true if this function is successful. hps contains 
the presentation space handle. IFirstchar contains the codepoint of 
the first character that you want width table information for. ICount 
contains the number of elements in alData. alData contains the 
width table information. You can retrieve the last error using 
WinGetLastError. These errors include: 


Ox2014 PMERR COORDINATE OVERFLOW 
0x2071 PMERR-INV FIRST CH-AR 
0x207F PMERR-INV-HPS 
0x2092 PMERR-INV-LENGTH OR COUNT 
0x20F4 PMERR-PS BUSY 


The GpiRectlnRegion function checks whether any part of a 
rectangle lies within the specified region. Ilnside contains the inside 
and error indicators. hps contains the presentation space handle. 
hrgn contains the region handle. prclBect contains the rectangle 
that you want to check in device coordinates. GpiRectlnRegion 
returns one of the following values: 


0000 RRGN ERROR 
0001 RRGN-OUTSIDE 
0002 RRGN-PARTIAL 
0003 RRGN-INSIDE 


You can retrieve the last error using WinGetLastError. These errors 
include: 


Ox2034 PMERR HRGN BUSY 
0x205B PMERR-INV C60RDINATE 
0x207F PMERR-INV-HPS 
0x2080 PMERR-INV-HRGN 


Function 


lvisibility = 
GpiBectvisible (hps, 
prclBectangle) 


fsuccess = 
GpiBemove- 
Dynamics (hps 
lFirstsegid, 
lLastsegid) 


fsuccess = 
GpiBesetBoundary- 
Data (hps) 


fsuccess = 
GpiBesetps (hps, 
floptions) 


Description 


Ox20BD PMERR INV RECT 
0x20F4 PMERR-PS BUSY 
0x20F8 PMERR-RE-GION IS CLIP REGION 


The GpiRectvisible function checks whether any part of a rectangle 
lies within the clipping region of the device associated with the 
specified presentation space. Ivisibility contains the visibility and 
error indicators. hps contains the presentation space handle. 
prclBectangle contains the rectangle that you want to check in 
world coordinates. GpiRectvisible returns one of the following 
values: 


0000 RVIS ERROR 
0001 RVIS-INVISIBLE 
0002 RVIS-PARTIAL 
0003 RVIS-VISIBLE 


You can retrieve the last error using WinGetLastError. These errors 
include: 


Ox205B PMERR INV COORDINATE 
0x207F PMERR-INV-HPS 
0x20BD PMERR-INV-RECT 
0x20F4 PMERR-PS BUSY 


The GpiRemoveDynamics function removes the parts of a displayed 
image drawn from the dynamic segments section of the segment 
chain. (This includes any parts drawn by calls from these dynamic 
segments.) fsuccess contains true if this function is successful. hps 
contains the presentation space handle. IFirstsegid contains the first 
segment in the section. ILastsegid contains the last segment in the 
section. You can retrieve the last error using WinGetLastError. 
These errors include: 


ox2o74 PMERR INv FOR THls Dc rvpE 
0x207F PMERR-INV-HPS 
0x20AI PMERR-INV-MICROPS FUNCTION 
0x20C8 PMERR-INV-SEG NAM-E 
0x20F4 PMERR-PS BUSY- 


The GpiResetBoundaryData function resets the boundary data to 
null. fsuccess contains true if this function is successful. hps 
contains the presentation space handle. You can retrieve the last 
error using WinGetLastError. These errors include: 


Ox207F PMERR INV HPS 
0x20F4 PMERR-PS BUSY 


The GpiResetps function resets the presentation space. fsuccess 
contains true if this function is successful. hps contains the 
presentation space handle. floptions contains one of three reset 
options including: GRES_AITRS, GRES_SEGMENTS, or 
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Function 


fsuccess = 
GpiBestoreps (hps, 
lpsid) 


fsuccess = 
GpiBotate (hps, 
pmatlfArray, 
IOptions, fxAngle, 
pptlcenter) 


fsuccess = 
GpisaveMetaFile 
(hmf, pszFilename) 


Description 


GRES_ALL. You can retrieve the last error using WinGetLastError. 
These errors include: 


Ox207F PMERR Irv Hps 
Ox20C2 PMERR-INV-RESET OPTIONS 
0x20F4 PMERR-PS BUSY 


The GpiRestoreps function restores the state of the presentation 
space to the one that existed when you issued the corresponding 
Gpisaveps call. ryou do not need to restore the most recent save; 
any interim saves are discarded.) fsuccess contains true if this 
function is successful. hps contains the presentation space handle. 
IPsid contains the identifier of the presentation space that you want 
to restore. You can retrieve the last error using WinGetLastError. 
These errors include: 


Ox207F PMERR INV HPS 
0x2081 PMERR-INV-ID 
0x20DE PMERR-Not IN DRAW MODE 
0x20F4 PMERR-PS B-USY 


The GpiRotate function applies a rotation to a transform matrix. 
fsuccess contains true if this function is successful. hps contains 
the presentation space handle. pmatlfArray contains the transform 
matrix. The first, second, fourth, and fifth elements are of type 
FIXED. They have an assumed binary point between the second and 
third bytes (1.0 is represented as 65,536). You must provide values 
of 0, 0, 1 for the third, sixth, and ninth elements respectively. 
IOptions contains the transform options, which include: 
TRANSFORM_REPLACE and TRANSFORM_ADD. fxAng le 
contains the rotation angle. pptlcenter contains the center of 
rotation. You can retrieve the last error using WinGetLastError. 
These errors include: 


Ox20D0 PMERR INV TRANSFORM TYPE 


The GpisaveMetaFile function saves a metafile to a disk file. (This 
action removes the metafile from memory and invalidates the 
handle). fsuccess contains true if this function is successful. hmf 
contains the metafile handle. pszFilename contains the name of the 
file that you want to use for storage. OS/2 does not allow you to use 
an existing filename. You can retrieve the last error using 
WinGetlrdstError. These errors include : 


Ox2024 PMERR DOSOPEN FAILURE 
0x203D PMERR-INSUFFICIENT DISK SPACE 
0x207E PMERR-INV HMF 
0x20D9 PMERR-METAFILE IN USE 
0x2106 PMERR-TOO MAN-Y fuETAFILES IN USE 


Function 


lpsid = Gpisaveps 
(hps) 


fsuccess = Gpiscale 
(hps, pmatlfArray, 
loptions, afxscale, 
pptlcenter) 


hpalold = 
Gpiselectpalette 
(hps, hpal) 


fsuccess = 
GpisetArcparams 
(hps, 
parcpArcparams) 


fsuccess = 


Description 


The Gpisaveps function saves information about the presentation 
space on a LIFO stack. IPsid contains the presentation space 
identifier (0 indicates an error). hps contains the presentation space 
handle. You can retrieve the last error using WinGetLastError. These 
errors include : 


Ox207F PMERR INV HPS 
0x20DF PMERR-Nor IN DRAW MODE 
0x20F4 PMERR-PS B-USY 


The Gpiscale function applies a scaling component to a transform 
matrix. fsuccess contains true if this function is successful. hps 
contains the presentation space handle. pmatlfArray contains the 
transform matrix. The first, second, fourth, and fifth elements are of 
type FIXED. They have an assumed binary point between the second 
and third bytes (1.0 is represented as 65,536). You must provide 
values of 0, 0, .1 for the third, sixth, and ninth elements respectively 
loptions contains the transform options, which include: 
TRANSFORM REpljACE and TRANSFORM ADD. afxscale is an 
array of scaling factors; the first element is the-X-scale factor and the 
second is the Y-scale factor. pptlcenter contains the center of scale. 
You can retrieve the last error using WinGetLastError. These errors 
include: 


Ox20D0 PMERR INV TRANSFORM TYPE 


The Gpiselectpalette function selects a palette into a presentation 
space. hpalold contains the old palette handle (NULLHANDLE if 
the application was using the default palette) or a -1 to indicate an 
error. hps contains the presentation space handle. hpal contains the 
palette handle. Providing a value of NULLHANDLE resets the 
presentation space to the default palette. You can retrieve the last 
error using WinGetLastError. These errors include: 


Ox203F 
0x207F 
0x2085 
0x20F4 
0x2 1 1 1 
0x2112 


PMERR INSUFFICIENT MEMORY 
PMERR-INV HPS 
PMERR-INV-IN AREA 
PMERR-PS BUSY 
PwiERR-INV-HPAL 
PMERR-PAL-EITE BUSY 


The GpisetArcparams function sets the current arc parameters. 
fsuccess contains true if this function is successful. hps contains 
the presentation space handle. parcpArcparams contains the arc 
parameters that consist of four elements: p, q, r, and s. You can 
retrieve the last error using WinGetLastError. These errors include: 


Ox205B PMERR INV COORDINATE 
0x207F PMERR-INV-HPS 
0x20F4 PMERR-PS BUSY 


The GpisetAttrMode function sets the current attribute mode. The 
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Function 


GpisetAttrMode 
(hps, lMode) 


fsuccess = 
GpisetAttrs (hps, 
lprimType, 
flAttrMask, 
flDefMask, 
ppbunAttrs) 


Description 


setting of this mode affects whether a primitive attribute is saved on 
the stack when another attribute replaces it. You can restore the 
original attribute using the Gpipop function. fsuccess contains true 
if this function is successful. hps contains the presentation space 
handle. IMode contains the attribute mode, which includes: 
AM PRESERVE and AM NOPRESERVE. You can retrieve the last 
erro-r using WinGetLastErTor. These errors include: 


Ox2043 PMERR INV AITR MODE 
0x2060 PMERR-INV-DC TtypE 
0x207F PMERR-INV-HP§ 
Ox20AI PMERR-INV-MICROPS FUNCTION 
0x20F4 PMERR-PS BUSY 


The GpisetAttrs function sets the attributes of the specified primitive 
type. fsuccess contains true if this function is successful. hps 
contains the presentation space handle. IprimType contains the 
primitive type that you want to change. This includes: PRIM_LINE, 
PRIM_CHAR, PRIM_MARKER, PRIM_AREA, and PRIM_IMAGE. 
flAttrMask contains the attributes mask. Each flag that you set 
indicates that there is a corresponding setting value in either 
flDefMask or ppbunAttrs. The line attributes include: 
LBB_COLOR, LBB_MIX_MODE, LBB_WIDTH , 
LBB_GEOM_WIDTH, LBB_TYPE, LBB_END, and LBB_JOIN. The 
character attribute types include: CBB_COLOR, 
CBB_BACK_COLOR, CBB_MIX_MODE, 
CBB_BACK_MIX_MODE, CBB_SET, CBB_MODE, CBB_BOX, 
CBB_ANGLE, CBB_SHEAR, and CBB_DIRECTION. The marker 
attribute types include: MBB_COLOR, MBB_BACK_COLOR, 
MBB_MIX_MODE, MBB_BACK_MIX_MODE, MBB_SET, 
MBB_SYMBOL, and MBB_BOX. The pattern attribute types 
include : ABB_COLOR, ABB_BACK_COLOR, ABB_MIX_MODE, 
ABB_BACK_MIX_MODE, ABB_SET, ABB_SYMBOL, and 
ABB_REF_POINT. The image attribute types include: IBB_COLOR, 
IBB_BACK_COLOR, IBB_MIX_MODE, and 
188 BACK MIX MODE. flDefMask contains the defaults mask. 
ppb-unAttrs-contains the attributes. Each primitive type uses its own 
structure as follows: LINEBUNDLE, CHARBUNDLE, 
MARKERBUNDLE, AREABUNDLE, and IMAGEBUNDLE. You can 
retrieve the last error using WinGetLastError. These errors include: 


Ox2035 
0x2044 
0x204B 
0x204C 
0x204D 
0x204F 


PMERR HUGE FONTS NOT SUPPORTED 
PMERR-INV BACKGROUND-COL ATTR 
PMERR-INV-CHAR ANGLE AITR- 
PMERR-INV-CHAR-DIRECTioN AITR 
PMERR-INV-CHAR-MODE AITR 
PMERR-INv-CHAR-SET AfrR 


Function 


fsuccess = 
GpisetBackcolor 
(hps, IColor) 


fsuccess = 
GpisetBackMix 
(hps, lMixMode) 


hbmold = 
GpisetBitmap (hps, 
hbm) 


Description 


Ox2050 PMERR INV CHAR SHEAR AITR 
0x2053 PMERR-INV-COLOR AITR 
0x205B PMERR-INV-COORDINATE 
0x2078 PMERR-INV-GEOM LINE WIDTH AITR 
0x207F PMERR-INV-HPS 
0x2093 PMERR-INV-LINE END AITR 
0x2094 PMERR-INV-LINE-JOIN-AITR 
0x2095 PMERR-INV-LINE-TYPE-AITR 
0x2096 PMERR-INV-LINE-WIDTFI AITR 
0x2099 PMERR-INV-MARKER SET AITR 
0x209A PMERR-INV-MARKER-SYM-BOL ATTR 
0x20A3 PMERR-INV-MIX ATTR 
Ox2OAF PMERR-INv-pAriERN ATTR 
0x2082 PMERR-INV-PATTERN-SET AITR 
0x20B9 PMERR-INV-PRIMITIVE TYPE 
0x20F4 PMERR-PS BUSY 
0x2109 PMERR-UN-SUPPORTED ATTR 
0x210A PMERR-UNSUPPORTED-AITR VALUE 
The GpisetBackcolor function sets the current background color 
index attribute to the specified value. Each primitive type gets set 
individually. fsuccess contains true if this function is successful. hps 
contains the presentation space handle. IColor contains the 
background color. You can use a color index number or one of the 
following values: CLR_FALSE, CLR_TRUE, CLR_DEFAULT, 
CLR_WHITE, CLR_BIACK, CLR_BACKGROUND, CLR_BLUE, 
CLR_RED, CLR_PINK, CLR_GREEN, CLR_CYAN, 
CLR_YELLOW, CLR_NEUTRAL, CLR_DARKGRAY, 
CLR_DARKBLUE, CLR_DARKRED , CLR_DARKPINK, 
CLR_DARKGREEN, CLR_DARKCYAN, CLR_BROWN, or 
CLR_PALEGRAY. You can retrieve the last error using 
WinGetLastError. These errors include: 
Ox2044 PMERR INV BACKGROUND COL AITR 
Ox2o7F PMERR-IRE-Hps 
Ox20F4 PMERR-PS BUSY 
The GpisetBackMix function individually sets the background mix 
attribute for each primitive type. fsuccess contains true if this 
function is successful. hps contains the presentation space handle. 
IMixMode controls the background color mix mode. You can use 
any of the following mix modes: BM_DEFAULT, BM_OR, 
BM_OVERPAINT, BM_XOR, or BM_LEAVEALONE. You can 
retrieve the last error using WinGetLastError. These errors include: 


Ox2044 PMERR INV BACKGROUND COL AITR 
0x207F PMERR-INV-HPS 
0x20F4 PMERR-PS BUSY 


The GpisetBitmap function selects a bitmap in a memory device 
context. hbmold contains the old bitmap handle, a NULLHANDLE 
(if there is no old bitmap handle), or a value of -1 to indicate an 
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Function 


lscanset = 
GpisetBitmapBits 
(hps, lscanstart, 
lscans, pbBuffer, 
pbmi2lnfoTable) 


fsuccess = 
GpisetBitmap- 
Dimension (hps, 
psizlBitmap 
Dimension) 


fsuccess = 
GpisetBitmapld 
(hps, hbm, lLcid) 


Description 


error. hps contains the presentation space handle. hbm contains the 
bitmap handle. You can retrieve the last error using 
WinGetLastError. These errors include: 


Ox2008 
0x2032 
0x203A 
0x207B 
0x207F 
0x20F4 


PMERR BITMAP IN USE 
PMERR-HBITMA-P BUSY 
PMERR-INCOMPATIBLE BITMAP 
PMERR-INV HBITMAP 
PMERR-INV-HPS 
PMERR-PS BUSY 


The GpisetBitmapBits functions transfers bitmap data from 
application storage to a bitmap. IScanset contains the number of 
scan lines actually sent (values can be equal to or greater than 0). A 
return value of -1 signifies an error. hps contains the presentation 
space handle. IScanstart contains the starting scan line number (0 is 
the bottom line). IScans contains the number of scan lines that you 
want to send. pbBuffer contains the bitmap data. pbmi2lnfoTable 
contains the bitmap information table (including the associated color 
table). You can retrieve the last error using WinGetLastError. These 
errors include: 


Ox2060 PMERR INV DC TYPE 
0x207F PMERR-INV-HP5 
0x208F PMERR-INV-INFO TABLE 
0x2092 PMERR-INV-LENG-TH OR COUNT 
0x20C4 PMERR-INV-SCAN ST-ART- 
Ox20E4 PMERR-NO -BITMA-P SELECTED 
0x20F4 PMERR-PS -BUSY 


The GpisetBitmapDimension function associates a width and height 
with a bitmap. The system does not use these settings. An 
application can retrieve them using the GpiQueryBitmapDimension 
function. fsuccess contains true if this function is successful. hps 
contains the presentation space handle. psizBitmapDimension 
contains the width and height of the bitmap (using units of 0.1 
millimeter). You can retrieve the last error using WinGetLastError. 
These errors include: 


Ox2032 PMERR HBITMAP BUSY 
0x207B PMERR-INV HBITMAP 


The GpisetBitmapld function tags a bitmap with a local identifier. 
This allows you to use it as a pattern set containing a single member. 
fsuccess contains true if this function is successful. hps contains 
the presentation space handle. hbm contains the bitmap handle. 
ILcid contains the local identifier. You can retrieve the last error 
using WinGetLastError. These errors include: 


Function 


fsuccess = 
GpisetcharAngle 
(hps, pgradlAngle) 


fsuccess = 
GpisetcharBox (hps, 
psizfxBox) 


fsuccess = 
GpisetcharBreak- 
Extra (hps, 
fxBreakExtra) 


fsuccess = 
GpisetcharDirection 
(hps, lDirection) 


Description 


Ox2008 
0x2032 
0x207F 
0x207B 
0x20CA 
0x20F4 
0x2102 


PMERR BITMAP IN USE 
PMERR-HBITMA-P gusY 
PMERR-INV HPS 
PMERR-INV-HBITMAP 
PMERR-INV-SETID 
PMERR-PS BUSY 
PMERR-SEilD IN USE 


The GpisetcharAngle function sets the baseline angle used to draw 
characters as a relative vector. fsuccess contains true if this 
function is successful. hps contains the presentation space handle. 
pgradlAngle contains the baseline angle as a coordinate (a gradient 
to the origin of 0, 0). Providing a value of 0, 0 resets the angle to 
default. The standard default is 1, 0. You can retrieve the last error 
using WinGetLastError. These errors include: 


Ox207F PMERR INV HPS 
0x20F4 PMERR-PS BUSY 


The GpisetcharBox function sets the current character-box attribute 
to the specified value. fsuccess contains true if this function is 
successful. hps contains the presentation space handle. psizfxBox 
contains the size of the box in world coordinates. You can retrieve 
the last error using WinGetLastError. These errors include: 


Ox207F PMERR INV HPS 
0x20F4 PMERR-PS BUSY 


The GpisetcharBreakExtra function specifies an extra increment 
used for spacing break characters in a string. fsuccess contains true 
if this function is successful. hps contains the presentation space 
handle. fxBreakExtra contains the character-break-extra value. 
Using a 0 value results in normal spacing, a negative value reduces 
the spacing, and a positive value increases spacing. You can retrieve 
the last error using WinGetLastError. These errors include: 


Ox207F PMERR INV HPS 
0x20F4 PMERR-PS BUSY 


The GpisetcharDirection function determines the direction OS/2 
draws characters along the baseline. fsuccess contains true if this 
function is successful. hps contains the presentation space handle. 
IDirection determines the character draw direction, which includes: 
CHDIRN_DEFAULT, CHDIRN_LEFTRIGHT, 
CHDIRN_TOPBOTTOM , CHDIRN_RIGHTLEFT, or 
CHDIRN_BOTroMTOP. You can retrieve the last error using 
WinGetLastError. These errors include: 


Ox204C PMERR INV CHAR DIRECTION AITR 
0x207F PMERR-INV-HPS 
0x20F4 PMERR-PS BUSY 
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Function 


fsuccess = 
GpisetcharExtra 
(hps, fxExtra) 


fsuccess = 
GpisetcharMode 
(hps, lMode) 


fsuccess = 
Gpisetcharset 
(hps, lLcid) 


fsuccess = 
Gpisetcharshear 
(hps, pptlAngle) 


fsuccess = 
Gpisetclippath (hps, 
lpath, loptions) 


Description 


The GpisetcharExtra function specified an extra increment used to 
space characters in a string. fsuccess contains true if this function 
is successful. hps contains the presentation space handle. fxExtra 
contains the character-extra value. Using a 0 value results in normal 
spacing, a negative value reduces the spacing, and a positive value 
increases spacing. You can retrieve the last error using 
WinGetlrdstError. These errors include: 


Ox207F PMERR INV HPS 
0x20F4 PMERR-PS BUSY 


The GpisetcharMode function sets the character mode used to 
draw a character string. fsuccess contains true if this function is 
successful. hps contains the presentation space handle. IMode 
contains the character mode, which includes: CM_DEFAULT, 
CM_MODE1, CM_MODE2, or CM_MODE3. You can retrieve the 
last error using WinGetLastError. These errors include: 


Ox204D PMERR INV CHARACTER MODE AITR 
0x207F PMERR-INV-HPS 
0x20F4 PMERR-PS BUSY 


The Gpisetcharset function sets the current value of the 
character-set attribute. fsuccess contains true if this function is 
successful. hps contains the presentation space handle. ILcid 
contains the character set local identifier, which includes: 
LCID_DEFAULT, or 1 through 254 for a logical font. You can 
retrieve the last error using WinGetLastError. These errors include: 


Ox2035 PMERR HUGE FONTS NOT SUPPORTED 
0x204F PMERR-INV CFIAR SET AFT-R 
0x207F PMERR-INV-HPS 
0x20F4 PMERR-PS BUSY 


The Gpisetcharshear function sets the character-shear attribute. 
fsuccess contains true if this function is successful. hps contains 
the presentation space handle. pptlAngle contains the shear angle 
as a coordinate (a gradient to the origin of 0, 0). You can retrieve 
the last error using WinGetLastError. These errors include: 


Ox2050 PMERR INV CHAR SHEAR AITR 
0x205B PMERR-INV-COOR-DINATE 
0x207F PMERR-INV-HPS 
0x20F4 PMERR-PS BUSY 


The Gpisetclippath function selects a path as the current clip path. 
fsuccess contains true if this function is successful. hps contains 
the presentation space handle. Ipath contains the path control flag. 
A value of 0 resets the current clip path to no clipping, while a value 


Function 


lcomplexity = 
GpisetclipBegion 
(hps, hrgn, 
phrgnold) 


fsuccess = 
Gpisetcolor (hps, 
lcolor) 


fsuccess = 
Gpisetcp (hps, 


Description 


of 1 intersects the current path with the defined path. IOptions 
contains the option bits, which include: SCP_ALTERNATE and 
SCP_WINDING. You can retrieve the last error using 
WinGetLastError. These errors include: 


Ox2051 PMERR INV CLIP PATH OPTIONS 
0x207F PMERR-INV-HPS 
0x20AE PMERR-INV-PATH ID 
0x20F4 PMERR-PS BUSY 
0x20FF PMERR-PATH UNKNOWN 


The GpisetclipRegion function sets the current clip region for any 
drawing that takes place through the specified presentation space. 
IComplexity contains the complexity of the resulting region or an 
error indicator on return from the function call. hps contains a 
presentation space handle. hrgn contains the region handle 
(NULLHANDLE resets clipping to no clipping). phrgnold contains 
a pointer to the old region handle. GpisetclipRegion returns one of 
the following values: 


0000 RGN ERROR 
0001 RGN-NULL 
0002 RGN-RECT 
0003 RGN-COMPLEX 


You can retrieve the last error using WinGetLastError. These errors 
include: 


Ox2034 PMERR HRGN BUSY 
0x207F PMERR-INV HPS 
0x2080 PMERR-INV-HRGN 
0x20F4 PMERR-PS BUSY 


The Gpisetcolor function sets the current color attribute for each 
primitive type. Each primitive type gets set individually. fsuccess 
contains true if this function is successful. hps contains the 
presentation space handle. IColor contains the foreground color. 
You can use a color index number or one of the following values: 
CLR_FALSE, CLR_TRUE, CLR_DEFAULT, CLR_WHITE, 
CLR_BLACK, CLR_BACKGROUND, CLR_BLUE, CLR_RED, 
CLR_PINK, CLR_GREEN, CLR_CYAN, CLR_YELLOW, 
CLR_NEUTRAL, CLR_DARKGRAY, CLR_DARKBLUE, 
CLR_DARKRED, CLR_DARKPINK, CLR_DARKGREEN, 
CLR_DARKCYAN, CLR_BROWN, or CLR_PALEGRAY. You can 
retrieve the last error using WinGetLastError. These errors include: 


Ox2053 PMERR INV COLOR AITR 
0x207F PMERR-INV-HPS 
0x20F4 PMERR-PS BUSY 


The Gpisetcp function sets the current graphics code page. 
fsuccess contains true if this function is successful. hps contains 


Table 3 -42 Continued 


Function 


ulcodepage) 


fsuccess = 
Gpisetcurrent- 
Position (hps, 
pptlpoint) 


fsuccess = 
GpisetDefArcparams 
(hps, 
parcpArcparams) 


fsuccess = 
GpisetDefAttrs (hps, 
lprimType, 
flAttrMask, 
ppbunAttrs) 


Description 


the presentation space handle. ulcodepage contains the code page 
identifier. You can retrieve the last error using WinGetLastError. 
These errors include: 


Ox2052 PMERR INV CODEPAGE 
0x207F PMERR-INV-HPS 
0x20F4 PMERR-PS BUSY 


The Gpisetcurrentposition function sets the current position to the 
specified point. This function is equivalent to the GpiMove function. 
It does save the current position on the stack if the AM_PRESERVE 
attribute is in effect. This allows you to restore the previous position 
using Gpipop. Each primitive type gets set individually. fsuccess 
contains true if this function is successful. hps contains the 
presentation space handle. pptlpoint contains the new position 
coordinates. You can retrieve the last error using WinGetLastError. 
These errors include: 


Ox205B PMERR INV COORDINATE 
0x207F PMERR-INV-HPS 
0x20F4 PMERR-PS BUSY 


The GpisetDefArcparams function sets the default arc parameters. 
The initial default values are: p=1, q=1, r=0, and s=0. Each 
primitive type gets set individually. fsuccess contains true if this 
function is successful. hps contains the presentation space handle. 
parcpArcparams contains the new default arc parameters in a four 
element structure (p, q, r, and s). You can retrieve the last error 
using WinGetLastError. These errors include: 


Ox205B PMERR INV COORDINATE 
0x207F PMERR-INV-HPS 
0x20F4 PMERR-PS BUSY 


The GpisetDefAttrs sets the default attributes for the specified 
primitive. fsuccess contains true if this function is successful. hps 
contains the presentation space handle. IprimType contains the 
primitive type that you want to change. This includes: PRIM_LINE, 
PRIM_CHAR, PRIM_MARKER, PRIM_AREA, and PRIM_IMAGE. 
flAttrMask contains the attributes mask. Each flag that you set 
indicates that there is a corresponding setting value in ppbunAttrs. 
The line attributes include: LBB_COLOR, LBB_MIX_MODE, 
LBB_WIDTH, LBB_GEOM_WIDTH, LBB_TYPE, LBB_END, and 
LBB_JOIN. The character attribute types include: CBB_COLOR, 
CBB_BACK_COLOR, CBB_MD{_MODE, 
CBB_BACK_MIX_MODE, CBB_SET, CBB_MODE, CBB_BOX, 
CBB_ANGLE, CBB_SHEAR, and CBB_DIRECTION. The marker 
attribute types include: MBB_COLOR, MBB_BACK_COLOR, 


Function 


fsuccess = 
GpisetDefaultview- 
Matrix (hps, lcount, 
pmatlfArray, 
loptions) 


Description 


MBB_MIX_MODE, MBB_BACK_MIX_MODE, MBB_SET, 
MBB_SYMBOL, and MBB_BOX. The pattern attribute types 
include: ABB_COLOR, ABB_BACK_COLOR, ABB_MIX_MODE, 
ABB_BACK_MIX_MODE, ABB_SET, ABB_SYMBOL, and 
ABB_REF_POINT. The image attribute types include: IBB_COLOR, 
IBB_BACK_COLOR, IBB_MIX_MODE, and 
IBB_BACK_MIX_MODE. ppbunAttrs contains the attributes. Each 
primitive type uses its own structure as follows: LINEBUNDLE, 
CHARBUNDLE, MARKERBUNDLE, AREABUNDLE, and 
IMAGEBUNDLE. You can retrieve the last error using 
WinGetLastError. These errors include: 


Ox2035 PMERR HUGE FONTS NOT SUPPORTED 
0x2044 PMERR-INV BACKGROUND-COL AITR 
0x204B PMERR-INV-CHAR ANGLE AITR 
0x204C PMERR-INV-CHAR-DIRECTioN AITR 
0x204D PMERR-INV-CHAR-MODE AITR 
Ox204F PMERR-INv-CHAR-SET AfrR 
0x2050 PMERR-INV-CHAR-SHEAR ATTR 
0x2053 PMERR-INV-COLOR ATTR 
0x205B PMERR-INV-COORDINATE 
0x2078 PMERR-INV-GEOM LINE WIDTH AITR 
0x207F PMERR-INV-HPS 
0x2093 PMERR-INV-LINE END AITR 
0x2094 PMERR-INV-LINE-JOIN-ATTR 
0x2095 PMERR-INV-LINE-TYPE-AITR 
0x2096 PMERR-INV-LINE-WIDTFI AITR 
0x2099 PMERR-INV-MARKER SET ATTR 
0x209A PMERR-INV-MARKER-SYM-BOL AITR 
0x20A3 PMERR-INV-MIX ATTR 
0x20AF PMERR-INV-PATTERN ATTR 
0x2082 PMERR-INV-PATTERN-SET AITR 
0x2083 PMERR-INV-PATTERN-SET-FONT 
0x20B9 PMERR-INV-PRIMITIVE TYPE 
0x20F4 PMERR-PS BUSY 
0x2109 PMERR-UN-SUPPORTED AITR 
0x210A PMERR-UNSUPPORTED-ATTR VALUE 


The GpisetDefviewMatrix function sets the default viewing 
transform that OS/2 applies to the entire picture. fsuccess 
contains true if this function is successful. hps contains the 
presentation space handle. ICount contains the number of elements 
in pmatlfArray. pmatlfArray contains the transform matrix. The 
first, second, fourth, and fifth elements are of type FIXED. They have 
an assumed binary point between the second and third bytes (1.0 is 
represented as 65,536). You must provide values of 0, 0, 1 for the 
third, sixth, and ninth elements respectively. IOptions contains the 
transform options, which include: TRANSFORM_REPLACE, 
TRANSFORM_ADD, and TRANSFORM_PREEMPT. You can 
retrieve the last error using WinGetLastError. These errors include: 
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Function 


fsuccess = 
GpisetDefTag (hps, 
ITag) 


fsuccess = 
GpisetDefviewing- 
Limits (hps, 
prclLimits) 


fsuccess = 
GpisetDrawcontrol 
(hps, lcontrol, lvalue) 


fsuccess = 
GpisetDrawingMode 
(hps, lMode) 


Description 


Ox207F PMERR INV HPS 
0x2092 PMERR-INV-LENGTH OR COUNT 
0x209B PMERR-INV-MATRIX -ELEivlENT 
0x20D0 PMERR-INV-TRANSF-ORM TYPE 
0x20F4 PMERR-PS BUSY 


The GpisetDefTag function specifies the default primitive tag value. 
fsuccess contains true if this function is successful. hps contains 
the presentation space handle. ITag contains the default tag 
identifier. You can retrieve the last error using WinGetLastError. 
These errors include: 


Ox207F PMERR INV HPS 
0x20AI PMERR-INV-MICROPS FUNCTION 
0x20F4 PMERR-PS BUSY 


The GpisetDefviewingLimits function sets the default viewing limits 
value. fsuccess contains true if this function is successful. hps 
contains the presentation space handle. prclLimits contains the 
default viewing limits. You can retrieve the last error using 
WinGetLastError. These errors include: 


Ox205B PMERR INV COORDINATE 
0x207F PMERR-INV-HPS 
0x20F4 PMERR-PS BUSY 


The GpisetDrawcontrol function sets options for the subsequent 
drawing operations. fsuccess contains true if this function is 
successful. hps contains the presentation space handle. IControl 
contains a drawing control which include the following: 
DCTL_ERASE , DCTL_DISPLAY, DCTL_BOUNDARY, 
DCTL_DYNAMIC, and DCTL_CORRELATE. Ivalue contains the 
requests value for the control, which includes: DCTL_OFF and 
DCTL_ON. You can retrieve the last error using WinGetlrdstError. 
These errors include: 


Ox2063 
0x2064 
0x207F 
0x2085 
0x2089 
0x208B 
0x208D 
0x20A0 
0x20F4 


PMERR INV DRAW CONTROL 
PMERR-INV-DRAW-VALUE 
PMERR-Irv-Hps 
PMERR-INV-IN AREA 
PMERR-INV-IN-ELEMENT 
PMERR-INV-IN-PATH 
PMERR-INV-IN-SEG 
PMERR-Irv-MI-cROps DRAw CONTROL 
PMERR-PS BUSY 


The GpisetDrawingMode function sets the drawing mode 
to control handle subsequent individual drawing primitive 
and attribute calls. fsuccess contains true if this function 
is successful. hps contains the presentation space handle. 


Function 


fsuccess = 
GpisetEditMode 
(hps, lMode) 


fsuccess = 
GpisetElement- 
Pointer (hps, 
lElement) 


fsuccess = 
GpisetElement- 
PointerAtLabel (hps, 
lLabel) 


Description 


lMode contains the mode to use for subsequent drawing calls. 
This includes: DM_DRAW, DM_RETAIN, and 
DM_DRAWANDRETAIN. You can retrieve the last error using 
WinGetLastError. These errors include: 


Ox2065 
0x207F 
0x2085 
0x2089 
0x208B 
0x208D 
0x20A1 
0x20F4 


PMERR INV DRAWING MODE 
PMERR-INV-HPS 
PMERR-INV-IN AREA 
PMERR-INV-IN-ELEMENT 
PMERR-INV-IN-PATH 
PMERR-INV-IN-SEG 
PMERR-INV-MI-CROPS FUNCTION 
PMERR-PS BUSY 


The GpisetEditMode function sets the current editing mode (insert 
or replace an element within the segment). fsuccess contains true if 
this function is successful. hps contains the presentation space 
handle. IMode contains the editing mode, which includes: 
SEGEM INSERT and SEGEM REPLACE. You can retrieve the last 
error using WinGetLastError. These errors include: 


Ox2069 PMERR INV EDIT MODE 
0x207F PMERR-INV-HPS 
0x2089 PMERR-INV-IN ELEMENT 
0x20AI PMERR-INV-MI-CROPS FUNCTION 
0x20F4 PMERR-PS BUSY 


The GpisetElementpointer function sets the element pointer to the 
specified position within the current segment. The element pointer 
normally points to the end of the segment. fsuccess contains true if 
this function is successful. hps contains the presentation space 
handle. IElement contains the number of the element that you want 
to point at. You can retrieve the last error using WinGetLastError. 
These errors include: 


Ox207F 
0x2089 
0x20A1 
0x20E2 
0x20E6 
0x20F4 


PMERR INV HPS 
PMERR-INV-IN ELEMENT 
PMERR-INV-MI-CROPS FUNCTION 
PMERR-Nof IN RETAIN MODE 
PMERR-NO eukRENT s-EG 
PMERR-PS-BUSY 


The GpisetElementpointerAtLabel functions sets the element 
pointer to point at the specified label within the current segment. 
The element pointer normally points to the end of the segment. 
fsuccess contains true if this function is successful. hps contains 
the presentation space handle. ILabel contains the label that you 
want to point at. You can retrieve the last error using 
WinGetLastError. These errors include: 


Ox207F PMERR INV HPS 
0x2089 PMERR-INV-IN ELEMENT 


Table 3 -42 Continued 


Function 


fsuccess = 
GpisetGraphicsField 
(hps, prclField) 


fsuccess = 
Gpisetlnitialsegment- 
Attrs (hps, lAttribute, 
lvalue) 


fsuccess = 
GpisetLineEnd (hps, 
lLineEnd) 


fsuccess = 
GpisetLineJoin (hps, 
lLineJoin) 


Description 


Ox20AI PMERR INV MICROPS FUNCTION 
0x20D6 PMERR-IAB-EL NOT F-OUND 
0x20E2 PMERR-NOT IN RET-AIN MODE 
0x20E6 PMERR-NO €UkRENT S-EG 
0x20F4 PMERR-PS -BUSY 


The GpisetGraphicsField function sets the size and position of the 
graphics fields (measured in presentation page units). fsuccess 
contains true if this function is successful. hps contains the 
presentation space handle. prclField contains the coordinates of the 
graphics field. You can retrieve the last error using WinGetLastError. 
These errors include: 


Ox205B PMERR INV COORDINATE 
0x207A PMERR-INV-GRAPHICS FIELD 
0x207F PMERR-INV-HPS 
0x20F4 PMERR-PS BUSY 


The GpisetlnitialsegmentAttrs function sets the segment attribute 
used when your application creates a segment. fsuccess contains 
true if this function is successful. hps contains the presentation 
space handle. IAttribute contains the segment attribute you want to 
set including : AITR_DETECTABLE, AITR_VISIBLE, 
ATTR_CHAINED , AITR_DYNAMIC , AITR_FASTCHAIN , 
ATTR_PROP_DETECTABLE, and AITR_PROP_VISIBLE. Ival ue 
contains the attribute value, which includes: AITR_ON and 
ATTR_OFF. You can retrieve the last error using WinGetLastError. 
These errors include: 


Ox207F PMERR INV HPS 
0x20AI PMERR-INV-MICROPS FUNCTION 
0x20C5 PMERR-INV-SEG ATTE 
0x20C6 PMERR-INV-SEG-ATTR VALUE 
0x20F4 PMERR-PS BUSY- 


The GpisetLineEnd function sets the current line-end attribute. 
fsuccess contains true if this function is successful. hps contains 
the presentation space handle. ILineEnd contains the line end style, 
which includes : LINEEND_DEFAULT, LINEEND_FLAT, 
LINEEND_SQUARE, and LINEEND_ROUND. You can retrieve the 
last error using WinGetLastError. These errors include: 


Ox207F PMERR INV HPS 
0x2093 PMERR-INV-LINE END AITR 
0x20F4 PMERR-PS BUSY- 


The GpisetLineJoin function sets the current line-join attribute. 
fsuccess contains true if this function is successful. hps contains 
the presentation space handle. ILineJoin contains the line join style, 


Function 


fsuccess = 
GpisetLineType 
(hps, fxLinewidth) 


GpisetLinewidth 


fsuccess = 
GpisetLinewidth- 
Geom (hps, 
lLinewidth) 


fsuccess = 
GpisetMarker (hps, 
lsymboI) 


Description 


which includes : LINEJOIN_DEFAULT, LINEJOIN_BEVEL, 
LINEJOIN_ROUND, and LINEJOIN_MITRE. You can retrieve the 
last error using WinGetLastError. These errors include: 


Ox207F PMERR INV HPS 
0x2094 PMERR-INV-LINE JOIN ATTR 
0x20F4 PMERR-PS BUSY- 


The GpisetLineType function sets the current cosmetic line-type 
attribute. fsuccess contains true if this function is successful. hps 
contains the presentation space handle. ILineType contains the line 
end style, which includes: LINETYPE_DEFAULT, LINETYPE_DOT, 
LINETYPE_SHORTDASH , LINETYPE_DASHDOT, 
LINETYPE_DOUBLEDOT, LINETYPE_LONGDASH , 
LINETypE_DASHDouBLEDOT, LINErvpE_SoLID , 
LINErvpE_ALTERNATE, and LINETYPE_INVISBLE. You can 
retrieve the last error using WinGetLastError. These errors include: 


Ox207F PMERR INV HPS 
0x2094 PMERR-INV-LINE TYPE ATTR 
0x20F4 PMERR-PS BUSY- 


The GpisetLinewidth function sets the current cosmetic line-width 
attribute. fsuccess contains true if this function is successful. hps 
contains the presentation space handle. fxLinewidth contains the 
line width multiplier, which includes: LINEWIDTH_DEFAULT, 
LINEWIDTH_NORMAL, and LINEWIDTH_THICK. You can 
retrieve the last error using WinGetLastError. These errors include: 


Ox207F PMERR INV HPS 
0x2096 PMERR-INV-LINE WIDTH AITR 
0x20F4 PMERR-PS BUSY- 


The GpisetLinewidthGeom function sets the current geometric 
line-width attribute. fsuccess contains true if this function is 
successful. hps contains the presentation space handle. ILinewidth 
contains the line width in world coordinates. You can retrieve the 
last error using WinGetLastError. These errors include: 


Ox207F PMERR INV HPS 
0x2078 PMERR-INV-GEOM LINE WIDTH AITR 
0x20F4 PMERR-PS BUSY 


The GpisetMarker function sets the value of the marker-symbol 
attribute. fsuccess contains true if this function is successful. hps 
contains the presentation space handle. Isymbol contains the 
marker symbol. 0 selects the default symbol. You can retrieve the 
last error using WinGetLastError. These errors include: 


Ox207F PMERR INV HPS 
0x209A PMERR-INV-MARKER SYMBOL AITR 
0x20F4 PMERR-PS BUSY 


Table 3 -42 Continued 


Function 


fsuccess = 
GpisetMarkerBox 
(hps, psizfxsize) 


GpisetMarkerset 


fsuccess = 
GpisetMetaFileBits 
(hmf, Ioffset, lLength, 
pbBuffer) 


fsuccess = 
GpisetMix (hps, 
lMixMode) 


Description 


The GpisetMarkerBox function sets the current marker-box 
attribute. fsuccess contains true if this function is successful. hps 
contains the presentation space handle. psizlfxsize contains the size 
of the marker box in world coordinates. You can retrieve the last 
error using WinGetLastError. These errors include: 


Ox207F PMERR INV HPS 
0x20F4 PMERR-PS BUSY 


The GpisetMarkerset function sets the current marker-set attribute. 
fsuccess contains true if this function is successful. hps contains 
the presentation space handle. Iset contains the marker set local 
identifier. You can use a value of LCID DEFAULT or an identifier in 
the range 1 to 254. You can retrieve tEe last error using 
WinGetLastError. These errors include: 


Ox207F PMERR INV HPS 
0x2099 PMERR-INV-MARKER SET ATTR 
0x20F4 PMERR-PS BUSY 


The GpisetMetaFileBits functions transfers metafile data from 
application storage to a memory metafile. fsuccess contains true if 
this function is successful. hmf contains the metafile handle. Ioffset 
contains the offset within the metafile where you want the transfer 
to start. ILength contains the length of the metafile data. pbBuffer 
contains the metafile data. You can retrieve the last error using 
WinGetLastError. These errors include: 


Ox207E PMERR INV HMF 
0x209E PMERR-INV-METAFILE LENGTH 
0x209F PMERR-INV-METAFILE-OFFSET 
0x20D9 PMERR-MET-AFILE IN 0SE 


The GpisetMix function individually sets the foreground mix 
attribute for each primitive type. fsuccess contains true if this 
function is successful. hps contains the presentation space handle. 
IMixMode controls the background color mix mode. You can use 
any of the following mix modes: FM_DEFAULT, FM_OR, 
FM_OVERPAINT, FM_XOR, FM_LEAVEALONE, FM_AND , 
FM_SUBTRACT, FM_MARKSRCNOT, FM_ZERO , 
FM_NOTMERGESRC, FM_NOTXORSRC , FM_INVERT, 
FM_MERGESRCNOT, FM_NOTCOPYSRC , FM_MERGENOTSRC, 
FM_NOTMASKSRC, or FM_ONE. You can retrieve the last error 
using WinGetLastError. These errors include: 


Ox207F PMERR INV HPS 
0x20A3 PMERR-INV-MIX AITR 
0x20F4 PMERR-PS BUSY 


Function 


fsuccess = 
GpisetModel- 
TransformMatrix 
(hps, ICount, 
pmatlfArray, 
loptions) 


fsuccess = 
Gpisetpageviewport 
(hps, prclviewport) 


fsuccess = 
GpisetpaletteEntries 
(hpal, ulFormat, 
ulstart, ulcount, 
aTable) 


Description 


The GpisetModelTransformMatrix function sets the model 
transform matrix for subsequent primitives. fsuccess contains true 
if this function is successful. hps contains the presentation space 
handle. ICount contains the number of elements in pmatlfArray. 
pmatlfArray contains the transform matrix. The first, second, 
fourth, and fifth elements are of type FIXED. They have an assumed 
binary point between the second and third bytes (1.0 is represented 
as 65,536). You must provide values of 0, 0, 1 for the third, sixth, 
and ninth elements, respectively. IOptions contains the transform 
options, which include: TRANSFORM_REPLACE, 
TRANSFORM_ADD, and TRANSFORM_PREEMPT. You can 
retrieve the last error using WinGetLastError. These errors include: 


Ox207F PMERR INV HPS 
0x2092 PMERR-INV-LENGTH OR COUNT 
0x209B PMERR-INV-MATRIX -ELEMENT 
0x20D0 PMERR-INV-TRANSF-ORM TYPE 
0x20F4 PMERR-PS BUSY 


The Gpisetpageviewport function sets the page viewport within the 
device space. fsuccess contains true if this function is successful. 
hps contains the presentation space handle. prclviewport contains 
the size and position of the page viewport in device units. You can 
retrieve the last error using WinGetLastError. These errors include: 


Ox205B PMERR INV COORDINATE 
0x207F PMERR-INV-HPS 
0x20AD PMERR-INV-PAGE VIEWPORT 
0x20F4 PMERR-PS BUSY 


The GpisetpaletteEntries function changes the entries in a palette. 
IVou will not see the results until you call WinRealizepalette.) 
fsuccess contains true if this function is successful. hpal contains 
the color palette handle. ulFormat contains the format of the table 
entries, which includes: LCOLF_CONSECRGB. ulstart contains the 
starting index. ulcount contains the number of entries in aTable. 
aTable is an array of color values. Each color value is a 4-byte 
integer with a value of (F x 16777216) + (B x 65536) + (G x 256) 
+ 8. F is one of the following flags: PC_RESERVED or 
PC_EXPLICIT. B, G, and 8 are the color values. You can retrieve 
the last error using WinGetLastError. These errors include: 


Ox2111 
0x2112 
0x203F 
0x2054 
0x2055 
0x2058 
0x2085 
0x2092 


PMERR INV HPAL 
PMERR-PAL-EITE BUSY 
PMERR-INSUFFICIENT MEMORY 
PMERR-INV COLOR D-ATA 
PMERR-INV-COLOR-FORMAT 
PMERR-INV-COLOR-START INDEX 
PMERR-INV-IN AREA 
PMERR-INV-LE-NGTH OR COUNT 
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Function 
fsuccess = 
Gpisetpattern (hps, 
lpatternsymbol) 


fsuccess = 
GpisetpatternBef- 
Point (hps, 
pptlBefpoint) 


fsuccess = 
Gpisetpatternset 
(hps, lset) 


lHits = Gpisetpel 
(hps, pptlpoint) 


Description 


The Gpisetpattern function sets the current value of the 
pattern-symbol attribute. fsuccess contains true if this function is 
successful. hps contains the presentation space handle. 
Ipatternsymbol contains the identifier of the shading symbol that 
you want to use in the range from 0 to 255 (0 selects the default 
pattern). Possible patterns include : PATSYM_DEFAULT, 
PATSYM_DENSEl through PATSYM_DENSE8 , PATSYM_VERT, 
PATSYM_HORIZ, PATSYM_DIAG 1 through PATSYM_DIAG4, 
PATSYM_NOSHADE , PATSYM_SOLID , PATSYM_HALFTONE, 
and PATSYM_BLANK. You can retrieve the last error using 
WinGetLastError. These errors include: 


Ox207F PMERR INV HPS 
0x20B0 PMERR-INV-PATTERN AITR 
0x20F4 PMERR-PS BUSY 


The GpisetpatternRefpoint function sets the current pattern 
reference point to the specified value. fsuccess contains true if this 
function is successful. hps contains the presentation space handle. 
pptlBefpoint contains the pattern reference point in world 
coordinates (the default setting is 0, 0). You can retrieve the last 
error using WinGetLastError. These errors include: 


Ox205B PMERR INV COORDINATE 
0x207F PMERR-INV-HPS 
0x20F4 PMERR-PS BUSY 


The Gpisetpatternset function sets the current pattern-set attribute 
to the specified value. fsuccess contains true if this function is 
successful. hps contains the presentation space handle. Iset 
contains the pattern set local identifier that can contain numbers in 
the range 1 to 254 or LCID_DEFAULT. You can retrieve the last 
error using WinGetLastError. These errors include: 


Ox2035 PMERR HUGE FONTS NOT SUPPORTED 
0x207F PMERR-INV HPS 
0x2082 PMERR-INV-PATTERN SET AITR 
0x2083 PMERR-INV-PAITERN-SET-FONT 
0x20F4 PMERR-PS BUSY 


The Gpisetpel function sets a pel color using the current color and 
mix. You must specify the pel position in world coordinates. IHits 
contains the correlation and error indicators. hps contains the 
presentation space handle. pptlpoint contains the pel position in 
world coordinates. Gpisetpel returns one of the following values: 


0000 GPI ERROR 
0001 GPI_OK 
0002 GPI_HITS 


Function 


fsuccess = 
GpisetpickAperture- 
Position (hps, 
pptlpick) 


fsuccess = 
GpisetpickAperture- 
Size (hps, loptions, 
psizlsize) 


fsuccess = 
Gpisetps (hps, 
psizlsize, floptions) 


Description 


You can retrieve the last error using WinGetLastError. These errors 
include: 


Ox205B PMERR INV COORDINATE 
0x207F PMERR-INV-HPS 
0x20F4 PMERR-PS BUSY 
The GpisetpickApertureposition function sets the center of the pick 
aperture in the presentation page space. This affects subsequent 
nonretained correlation operations. fsuccess contains true if this 
function is successful. hps contains the presentation space handle. 
pptlpick contains the center of the pick aperture in presentation 
page coordinates. You can retrieve the last error using 
WinGetLastError. These errors include: 


Ox205B PMERR INV COORDINATE 
0x207F PMERR-INV-HPS 
0x20F4 PMERR-PS BUSY 
The GpisetpickAperturesize function sets the pick aperture size. 
fsuccess contains true if this function is successful. hps contains 
the presentation space handle. IOptions contains the setting 
options, which include: PICKAP_DEFAULT and PICKAP_REC. 
psizlsize contains the pick aperture size. You can retrieve the last 
error using WinGetLastError. These errors include: 
Ox207F PMERR INV HPS 
0x2084 PMERR-INV-PICK APERTURE OPTION 
0x2086 PMERR-INV-PICK-APERTURE-SIZE 
0x20F4 PMERR-PS BUSY 


The Gpisetps sets the presentation space size, units, and format. 
fsuccess contains true if this function is successful. hps contains 
the presentation space handle. psizlsize contains the presentation 
space size. floptions contains the presentation options. Each field 
provides one or more values as follow. The PS_UNITS field can 
contain: PU_ARBITRARY, PU_PELS, PU_LOMETRIC, 
PU_HIMETRIC, PU_LOENGLISH, PU_HIENGLISH, or 
PU_TWIPS. The PS_FORMAT field can contain: GPIF_DEFAULT, 
GPIF_SHORT, or GPIF_LONG. The PS_TYPE field contains the 
presentation space type (this value is ignored). The PS_MODE field 
contains the presentation space mode information (this value is 
ignored). The PS_ASSOCIATE field contains the association 
indicator (this value is ignored). The PS_NORESET field contains the 
inhibit full reset field. You can retrieve the last error using 
WinGetLastError. These errors include: 


Ox2074 
0x207C 
0x207F 
0x20A9 
0x20BA 
0x20F4 


PMERR INV FOR THIS DC TYPE 
PMERR-INV-HDC- 
PMERR-INV-HPS 
PMERR-INV-OR INCOMPAT OPTIONS 
PMERR-INV-PS-SIZE 
PMERR-PS BUS-Y 
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Function 


fsuccess = 
GpisetBegion (hps, 
hrgn, lcount, 
arclBectangles) 


fsuccess = 
GpisetsegmentAttrs 
(hps, lsegid, 
lAttribute, Ivalue) 


fsuccess = 
Gpisetsegment- 
Priority (hps, lsegid 
lBefsegid, Iorder) 


Description 


The GpisetRegion function changes a region to the logical-OR of 
the rectangles that define it. fsuccess contains true if this function 
is successful. hps contains the presentation space handle. hrgn 
contains the region handle. ICount contains the number of elements 
in arclBectangles. arclBectangles contains an array of rectangles 
specified in device coordinates. You can retrieve the last error using 
WinGetLastError. These errors include: 


Ox2034 PMERR HRGN BUSY 
0x205B PMERR-INV C60RDINATE 
0x207F PMERR-INV-HPS 
0x2080 PMERR-INV-HRGN 
0x2092 PMERR-INV-LENGTH OR COUNT 
0x20BD PMERR-INV-RECT 
0x20F4 PMERR-PS BUSY 
0x20F8 PMERR-REt;ION IS CLIP REGION 


The GpisetsegmentAttrs function sets a segment attribute. 
fsuccess contains true if this function is successful. hps contains 
the presentation space handle. Isegid contains the segment 
identifier. IAttribute contains the segment attributes. This includes: 
AITR_DETECTABLE , AITR_VISIBLE , ATTR_CHAINED , 
AITR_DYNAMIC , AITR_FASTCHAIN , 
AITR_PROP_DETECTABLE, and AITR_PROP_VISIBLE. Ival ue 
contains the attribute value, which includes: AITR_ON and 
ATTR_OFF. You can retrieve the last error using WinGetlrdstError. 
These errors include: 


Ox207F PMERR INV HPS 
0x20AI PMERR-INV-MICROPS FUNCTION 
0x20C5 PMERR-INV-SEG AITk 
Ox20C6 PMERR-INV-SEG-AITR VALUE 
0x20C8 PMERR-INV-SEG-NAME- 
Ox20F4 PMERR-PS BUSY- 
Ox2100 PMERR-SE6 NOT FOUND 


The Gpisetsegmentpriority function changes the position of a 
segment within the segment chain. It also can add a segment to the 
chain. fsuccess contains true if this function is successful. hps 
contains the presentation space handle. Isegid contains the 
segment identifier of the segment that you want to change. 
IBefsegid contains the identifier of the reference segment. OS/2 
places the segment that you want to change before or after the 
reference segment. Iorder determines the position of the segment 
when you change it. This parameter can have two values: 
LOWER_PRI or HIGHER_PRI. You can retrieve the last error using 
WinGetLastError. These errors include : 


Function 


Success = 
=pisetsegment- 
-ransformMatrix 


hps, lsegid, lcount, 
)matlfArray, 
Options) 


Success = 
=pisetstopDraw 
hps, lvalue) 


Success = 
=pisetTag (hps, 
rag) 


Success = 


Description 


Ox207F 
0x20A1 
0x20AB 
0x20C8 
0x20F4 
0x20FA 
0x2100 


PMERR INV HPS 
PMERR-INV-MICROPS FUNCTION 
PMERR-INv-ORDERING PARM 
PMERR-INV-SEG NAME- 
PMERR-PS BUSY- 
pMERR-sEa AND REFSEG ARE SAME 
PMERR-SEG-NOT-FOUND 


The GpisetsegmentTransformMatrix function sets the segment 
transform that normally applies to all primitives in the specified 
segment. fsuccess contains true if this function is successful. hps 
contains the presentation space handle. Isegid contains the 
segment identifier. ICount contains the number of elements in 
pmatlfArray. pmatlfArray contains the transform matrix. The first, 
second, fourth, and fifth elements are of type FIXED. They have an 
assumed binary point between the second and third bytes (1.0 is 
represented as 65,536). You must provide values of 0, 0, 1 for the 
third, sixth, and ninth elements respectively. IOptions contains the 
transform options, which include: TRANSFORM_REPLACE, 
TRANSFORM_ADD, and TRANSFORM_PREEMPT. You can 
retrieve the last error using WinGetLastError. These errors include: 


Ox207F 
0x2092 
0x209B 
0x20A1 
0x20C8 
0x20D0 
0x20F4 
0x2100 


PMERR INV HPS 
PMERR-INV-LENGTH OR COUNT 
PMERR-INV-MATRIX-ELEivlENT 
PMERR-INV-MICROP-S FUNCTION 
PMERR-INV-SEG NAM-E 
PMERR-INV-TRA-NSFORM TYPE 
PMERR-PS BUSY 
PMERR-sEa NOT FOuND 


The GpistopDraw function sets or clears the "stop draw" condition. 
fsuccess contains true if this function is successful. hps contains 
the presentation space handle. Ivalue contains the stop draw 
condition: SDW_OFF or SDW ON. You can retrieve the last error 
using WinGetLastError. These -errors include : 


Ox207F PMERR INV HPS 
0x20AI PMERR-INV-MICROPS FUNCTION 
0x20CF PMERR-INV-STOP DRAW VALUE 


The GpisetTag function sets the tag used to reference the following 
primitives. fsuccess contains true if this function is successful. hps 
contains the presentation space handle. ITag contains the tag 
identifier. You can retrieve the last error using WinGetLastError. 
These errors include: 


Ox207F PMERR INV HPS 
0x20AI PMERR-INV-MICROPS FUNCTION 
0x20F4 PMERR-PS BUSY 


The GpisetTextAlignment function determines the alignment of the 
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Function 


GpisetTextAlignment 
(hps, lHorizontal, 
lvertical) 


fsuccess = 
GpisetviewingLimits 
(hps, prclLimits) 


fsuccess = 
Gpisetviewing- 
TransformMatrix 
(hps, lcount, 
pmatlfArray, 
IOptions) 


lHits = Gpistroke- 
Path (hps, lpath, 
floptions) 


Description 


characters in a string. fsuccess contains true if this function is 
successful. hps contains the presentation space handle. IHorizontal 
contains the horizontal alignment. Ivertical contains the vertical 
alignment. You can retrieve the last error using WinGetLastError. 
These errors include: 


Ox207F PMERR INV HPS 
0x20F4 PMERR-PS BUSY 
0x2117 PMERR-INV CHAR ALIGN AITR 


The GpisetviewingLimits function sets a clipping rectangle in model 
space. fsuccess contains true if this function is successful. hps 
contains the presentatiori space handle. prclLimits contains the 
viewing limits in model space. You can retrieve the last error using 
WinGetLastError. These errors include: 


Ox205B PMERR INV COORDINATE 
0x207F PMERR-INV-HPS 
0x20F4 PMERR-PS BUSY 


The GpisetviewingTransformMatrix function sets the viewing 
transform that OS/2 applies to any subsequently opened segments. 
fsuccess contains true if this function is successful. hps contains 
the presentation space handle. ICount contains the number of 
elements in pmatlfArray. pmatlfArray contains the transform 
matrix. The first, second, fourth, and fifth elements are of type 
FIXED. They have an assumed binary point between the second and 
third bytes (1.0 is represented as 65,536). You must provide values 
of 0, 0, 1 for the third, sixth, and ninth elements respectively. 
IOptions contains the transform options, which include: 
TRANSFORM_REPIACE, TRANSFORM_ADD , and 
TRANSFORM_PREEMPT. You can retrieve the last error using 
WinGetLastError. These errors include: 


Ox207F 
0x208D 
0x2092 
0x209B 
0x20A1 
0x20D0 
0x20E2 
0x20F4 


PMERR INV HPS 
PMERR-INV-IN SEG 
PMERR-INV-LE-NGTH OR COUNT 
PMERR-Irv-MATRlx-ELEivlENT 
PMERR-INV-MICROP-S FUNCTION 
PMERR-INV-TRANSFO-RM TYPE 
PMERR-Not IN RETAIN rrioDE 
PMERR-PS B-USY 


The Gpistrokepath function strokes a path, then draws it. IHits 
contains the correlation and error indicators. hps contains the 
presentation space handle. Ipath contains the identifier to stroke 
(must contain 1). floptions contains the stroke option (reserved, set 
it to zero). Gpisetpel returns one of the following values: 


Function 


fsuccess = 
GpiTranslate (hps, 
pmatlfArray, loptions 
pptlTranslation) 


fsuccess = 
GpiunloadFonts 
(hps, pszFilename) 


Gpiunloadpublic- 
Fonts 


lHits = GpiwcBitBlt 
(hpsTarget, 
hbmsource, lcount, 
aptlpoints, IBop, 
floptions) 


Description 


0000 GPI ERROR 
0001 GPI_OK 
0002 GPI_HITS 


You can retrieve the last error using WinGetLastError. These errors 
include: 


Ox207F PMERR INV HPS 
0x20AE PMERR-INV-PATH ID 
0x20CI PMERR-INV-RESERVED FIELD 
0x20F4 PMERR-PS BUSY 
0x20FF PMERR-PATH UNKNOWN 


The GpiTranslate function applies a translation to a translation 
matrix. fsuccess contains true if this function is successful. hps 
contains the presentation space handle. pmatlfArray contains the 
transform matrix. The first, second, fourth, and fifth elements are of 
type FIXED. They have an assumed binary point between the 
second and third bytes (1.0 is represented as 65,536). You must 
provide values of 0, 0, 1 for the third, sixth, and ninth elements 
respectively. IOptions contains the transform options, which 
include : TRANSFORM_REPIACE, and TRANSFORM_ADD. 
pptlTranslation contains the coordinates of a point, relative to the 
origin, that defines the required translation. You can retrieve the last 
error using WinGetLastError. These errors include: 


Ox20D0 PMERR INV TRANSFORM TYPE 


The GpiunloadFonts function unloads any fonts previously loaded 
by GpiLoadFonts. fsuccess contains true if this function is 
successful. hps contains the presentation space handle. 
pszFilename contains the fully qualified font name. (OS/2 assumes 
an extension of FON.) You can retrieve the last error using 
WinGetLastError. These errors include : 


Ox202E PMERR FONT FILE NOT LOADED 
0x20EB PMERR-OWN -SET TD RE-FS 


The GpiunloadFonts function unloads one or more generally 
available fonts previously loaded by GpiLoadpublicFonts. fsuccess 
contains true if this function is successful. hps contains the 
presentation space handle. pszFilename contains the fully qualified 
font name. (OS/2 assumes an extension of FON.) You can retrieve 
the last error using WinGetLastError. These errors include: 


Ox202E PMERR FONT FILE NOT LOADED 
0x20EB PMERR-OWN -SET TD RE-FS 


The GpiwcBitBlt function copies a rectangle of bitmap image data. 
IHits contains the correlation and error indicators. hpsTarget 
contains the presentation space handle of the target. hbmsource 
contains the source bitmap handle. ICount contains the point count 
(must contain a value of 4). aptlpoints contains an array of lcount 
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Function 
Description 


points. These points are: Txl, Tyl, Tx2, Ty2, Sxl, Syl, Sx2, and 
Sy2. The first set of points is the bottom-left corner. The second set 
of points is the upper-right corner. IBop contains the mixing 
function required. There are 15 different mixing actions including: 
ROP_SRCCOPY, ROP_SRCPAINT, ROP_SRCAND, 
ROP_SRCINVERT, ROP_SRCERASE , ROP_NOTSRCCOPY, 
ROP_NOTSRCERASE, ROP_MERGECOPY, ROP_MERGEPAINT, 
ROP_PATCOPY, ROPPATPAINT, ROP_PATINVERT, 
ROP_DSTINVERT, ROP_ZERO, and ROP_ONE. floptions 
contains a list of applicable options. You can use bits 15 through 31 
for unique modes supported by particular devices. Other values for 
this parameter include: BBO_OR, BOO_AND, and BBO_IGNORE. 
GpiwcBitBlt returns one of the following values: 


0000 GPI ERROR 
0001 GPI_OK 
0002 G_PI HITS 


You can retrieve the last error using WinGetLastError. These errors 
include: 


Ox200A PMERR BITMAP NOT FOUND 
0x2032 PMERR-HBITMA-P BUSY 
0x203A PMERR-INCOMPATIBLE BITMAP 
ox2o3c PMERR-INcoRRECT D5 rvpE 
0x2046 PMERR-INV BITBLT-MIX- 
Ox2047 PMERR-INV-BITBLT-STYLE 
0x205B PMERR-INV-COORD-INATE 
0x207B PMERR-INV-HBITMAP 
0x207F PMERR-INV-HPS 
0x2092 PMERR-INV-LENGTH OR COUNT 
0x20BD PMERR-INV-RECT 
0x20E4 PMERR-NO -BITMAP SELECTED 
0x20F4 PMERR-PS -BUSY 


WIN functions 


Everything that you do with the Presentation Manager (PM) is based 
on a window. One of the very first things that you do when you write 
a PM application is create one or more windows. Every activity seems 
to involve some interaction with windows. The WIN functions work 
within windows; the device aspect of using these functions is hidden 
from the programmer in many cases. Very few WIN functions even 


mention the device context or the presentation space; their sole 
concern is the window. The WIN functions allow you to create, delete, 
and manipulate the windows required to create a PM application. 


Many of the WIN functions appear to overlap the GPI functions. In 
most cases, the GPI function is more accurate than its faster WIN 
counterpart. This is an important programming consideration. If you 
need speed, then use the WIN version of the function. If you need 
accuracy, use the GPI version. A perfect example of this relationship 
is the WinsubtractRect and GpicombineRegion functions. Both of 
them perform about the same task. The main difference between 
these two functions is their speed and accuracy. The WinsubtractRect 
function is much faster than its GpicombineRegion counterpart. 
Keep these differences in mind as you select functions for your 
applications. 


Table 3-43 contains a complete listing of the WIN function. It includes 
the calling syntax, a brief description of what task the function 
performs, and descriptions of each variable that the function requires. 
The table also includes references to other functions that act like the 
current function or that you need to call before calling this function. 
The descriptions contain any pertinent notes and warnings but might 
not tell you about every facet of the function. 


WIN function listing 
Table 3-43 


Function 


atom = WinAddAtom 
(hatomtblAtomTbl, 
pszAtomName) 


hswitchswitch = 
WinAddswitchEntry 


Description 


The WinAddAtom function adds an atom to an atom table. 
An integer atom always adds a new element to the table. A 
name atom updates the atom count by one if the atom already 
exists, or it adds a new atom if it does not exist. atom contains 
the atom associated with the passed string (0 indicates an 
error). hatomtblAtomTbl contains the atom table handle. 
pszAtomName contains the atom name. You can retrieve the 
last error using WinGetLastError. These errors include: 


Oxl013 PMERR INVALID HATOMTBL 
0xl015 PMERR-INVALID-ATOM NAME 
0xl016 PMERR-INVALID-INTEGER ATOM 
0xl017 PMERR-ATOM N-AME NOT-FOUND 


The WinAddswitchEntry function adds an entry to the 
Window List. (This is the list of applications displayed to the 
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Function 


(pswctlswitchData) 


mesult = WinAlarm 
(hwndDesktop, flstyle) 


fsuccess = 
WinAssociateHelplnstance 
(hwndHelplnstance, 
hwndApp) 


Henum = 
WinBeginEnumwindows 
(hwndparent) 


hpspaintps = 
WinBeginpaint (hwnd, 
hps, prclBect) 


Description 


user by the operating system.) hswitchswitch contains the 
Window List handle (NULLHANDLE indicates an error). 
pswctlswitch Data contains information about the Window 
List entry. You can retrieve the last error using 
WinGetLastError. These errors include : 


Oxl201 PMERR NO SPACE 
0xl206 PMERR-INVALID WINDOW 
0xl20B PMERR-INVALID-SESSION ID 


The WinAlarm function generates an audible alarm. fBesult 
contains true if this function is successful. hwndDesktop can 
contain HWND_DESKTOP or a handle to another desktop 
window. flstyle determines the type of alarm, which includes: 
WA_WARNING, WA_NOTE, and WA_ERROR. You can 
retrieve the last error using WinGetlrdstError. These errors 
include: 


Oxl001 PMERR INVALID HWND 
0xl019 PMERR-INVALID-FLAG 


The WinAssociateHelplnstance function associates the 
specified instance of the Help Manager with the window 
chain of the specified application window. fsuccess contains 
true if this function is successful. hwndHelplnstance contains 
a handle of an instance of the Help Manager. A value of 
NULLHANDLE disassociates the Help Manager instance from 
the window chain. hwndApp contains the handle of an 
application window. 


The WinBeginEnumwindows function starts the enumeration 
process for all immediate child windows of a specified 
window. Enumeration does not extend to the children of the 
child windows. Henum contains the enumeration handle. Use 
it with the WinGetNextwindow function to return the 
immediate child-window handles in succession. hwndparent 
contains the handle of the parent window. You can use the 
following values: HWND_DESKTOP, HWND_OBJECT, or 
any other window handle. You can retrieve the last error using 
WinGetLastError. These errors include: 


Oxl001 PMERR INVALID HWND 


The WinBeginpaint function obtains a presentation space. It 
readies the associated update region for drawing in a specified 
window. hpspaintps contains a presentation space handle 
(NULLHANDLE indicates an error). hwnd contains the 
window handle (HWND_DESKTOP or other window handle). 
hps contains the presentation space handle. NULLHANDLE 


Function 


fsuccess = 
WinBroadcastMsg 
(hwndparent, ulMsgld, 
mpparaml , mpparam2, 
flcmd) 


fsuccess = 
WincalcFrameBect (hwnd, 
prclBect, fFrame) 


f HookBet = 
WincallMsgFilter (hab, 
pqmsgpqmsg, ulFilter) 


fsuccess = 
Wincancelshutdown (hmq, 
fcancelAlways) 


ulBetcode = 
WinchangeswitchEntry 
(hswitchswitch, 
pswctlswitchData) 


Description 


obtains a cache presentation space. prclBect contains 
the bounding rectangle coordinates. A value of NULL 
indicates that the window does not require repainting. 
You can retrieve the last error using WinGetLastError. 
These errors include: 


Oxl001 PMERR INVALID HWND 
0x207F PMERR-INV HPS- 


The WinBroadcastMsg function broadcasts a message to 
multiple windows. This function posts messages to all the 
immediate child windows of hwndparent unless flcmd is 
BMSG DESCENDANTS. fsuccess contains true if this 
functiofi is successful. hwndparent contains the parent 
window handle. ulMsgld contains the message identifier. 
mpparaml contains the first parameter. mpparam2 contains 
the second parameter. flcmd contains the broadcast message 
command, which includes: BMSG_POST, BMSG_SEND, 
BMSG_POSTQUEUE, BMSG_DESCENDANTS, and 
BMSG FRAMEONLY. 


The WincalcFrameRect function calculates a client rectangle 
from a frame rectangle or a frame rectangle from a client 
rectangle. fsuccess contains true if this function is successful. 
hwnd contains the frame window handle. prclBect contains 
the coordinates of the window rectangle. fFrame contains the 
frame indicator: TRUE (frame rectangle provided) or FALSE 
(child-area rectangle provided). You can retrieve the last error 
using WinGetLastError. These errors include: 


Oxl001 PMERR INVALID HWND 


The WincallMsgFilter function calls a message-filter hook. 
fHookBet contains true if this function is successful. hab 
contains the anchor block handle. pqmsgpqmsg contains 
the message that you want to send to the message-filter hook. 
ulFilter contains the message-filter code that you want to pass 
to the message-filter hook. 


The Wincancelshutdown function cancels a request to shut 
an application down. fsuccess contains true if this function is 
successful. hmq contains the message queue handle for the 
current thread. fcancelAlways contains TRUE if you do not 
want to place a WM_QUIT message on the queue during 
system shutdown, or FALSE if the application will ignore any 
outstanding WM_QUIT messages, but you want it to receive 
the message during any other system shutdowns. 


The WinchangeswitchEntry function changes the 
information in a Window List entry. usBetcode contains a 0 
for successful completion, any other value is an error 
indication. hswitchswitch contains the Window List handle. 
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Function 


usBetchkst = 
WincheckButton 
(hwndDlg, usld, 
uschkstate) 


fsuccess = 
WincheckMenultem 
(hwndMenu, usld, fcheck) 


fsuccess = 
Wincloseclipbrd (hab) 


ulF3esult = 
Wincomparestrings (hab, 
idcodepage, 
idcountrycode, pszstringl 
pszstring2, floptions) 


ulcopied = 
WincopyAccelTable 
(hAccel, 
pacctAccelTable, 
ulcopyMax) 


Description 


pswctlswitchData contains information about the Window 
List entry. You can retrieve the last error using 
WinGetLastError. These errors include: 


Oxl202 PMERR INVALID SWITCH HANDLE 
0xl206 PMERR-INVALID-WINDOW- 


The WincheckButton function sets the checked state of the 
specified control button. It returns the previous state of the 
button. usBetchkst contains the previous button value. 
hwndDlg contains the dialog window handle. usld contains 
the button control identity. uschkstate contains the current 
checked state of the button. 


The WincheckMenultem function sets the check state of the 
specified menu item. fsuccess contains true if this function is 
successful. hwndMenu contains the menu window handle. 
usld contains the item identity. fcheck contains the current 
checked state of the item. 


The Wincloseclipbrd function closes the clipboard. This 
allows other applications to open it using the 
Winopenclipbrd function. fsuccess contains true if this 
function is successful. hab contains the anchor block handle. 


The Wincomparestrings function compares two 
null-terminated strings. They must use the same code page. 
ulBesult contains the comparison result or an error indicator. 
hab contains the anchor block handle. idcodepage contains 
the codepage identity for both strings. idcountrycode 
contains the country code. pszstringl and pszstring2 
contain the strings that you want to compare. floptions is a 
reserved parameter (set it to 0). Wincomparestrings returns 
one of the following values: 


0000 WIN ERROR 
0001 WIN:EQ 
0002 WIN LT 
0003 WIN_GT 


You can retrieve the last error using WinGetLastError. These 
errors include: 


Oxl00B PMERR INVALID STRING PARM 


The WincopyAccelTable function retrieves accelerator table 
data corresponding to an accelerator table handle. You also can 
use it to determine the size of the accelerator table data. 
ulcopied contains the amount of data copied into the data area 
or the size of the data area required for the complete 
accelerator table (0 indicates an error). hAccel contains the 


Function 


fsuccess = 
WincopyBect (hab, 
prclDest, prclsrc) 


ucDest = 
WincpTranslatechar 
(hab, idcpsource, 
ucSource, idcpDest) 


fsuccess = 
WincpTranslatestring 
(hab, idcpsource, 
pszSource, idcpDest, 
cbLenDest, pszDest) 


hAccel = 
WincreateAccelTable 
(hab, pacctAccelTable) 


hatomtblAtomTbl = 
WincreateAtomTable 
(ullnitial, ulBuckets) 


Description 


accelerator table handle. pacctAccelTable contains a pointer to 
the accelerator table data area (NULL if you want OS/2 to return 
the size of the accelerator table in bytes). ulcopyMax contains 
the size of the data area. You can retrieve the last error using 
EinGetLastError. These errors include : 


Oxl01A PMERR INVALID HACCEL 


The WincopyRect function copies a rectangle from prclsrc to 
prclDest. fsuccess contains true if this function is successful. 
hab contains the anchor block handle. prclDest is a pointer to 
the destination rectangle. prclsrc is a pointer to the source 
rectangle. 


The WincpTranslatechar function translates a character from 
one codepage to another. (If a character does not directly map 
to the new codepage, OS/2 uses a substitution character.) 
ucDest contains the converted character (0 indicates an error). 
hab contains the anchor block handle. idcpsource contains the 
source character codepage. ucSource contains the character that 
you want to translate. idcpDest contains the destination character 
codepage. You can retrieve the last error using WinGetLastError. 
These errors include: 


Oxl00B PMERR INVALID STRING PARM 
0xl01D PMERR-INVALID-SRC CO-DEPAGE 
0xl01E PMERR-INVALID-DST-CODEPAGE 


The WincpTranslatestring function translates a string from one 
codepage to another. (If a character does not directly map to the 
new codepage, OS/2 uses a substitution character.) fsuccess 
contains true if this function is successful. hab contains the 
anchor block handle. idcpsource contains the source character 
codepage. pszSource contains the string that you want to 
translate. idcpDest contains the destination character codepage. 
cbLenDest contains the length of the output string. pszDest 
contains the converted string. You can retrieve the last error using 
WinGetLastError. These errors include: 


Oxl003 PMERR PARAMETER OUT OF RANGE 
0xl00B PMERR-INVALID STR-ING EFAR-M 
0xl01D PMERR-INVALID-SRC CO-DEPAGE 
0xl01E PMERR-INVALID -DST-CODEPAGE 


The WincreateAccelTable function creates an accelerator table 
from the accelerator definitions in memory. hAccel contains the 
accelerator table handle. hab contains the anchor block handle. 
pacctAccelTable contains a pointer to the accelerator table. 
The WincreateAtomTable creates an atom table of the specified 
size. The minimum atom table size is 16+(2 x ulBuckets). 
hatomtblAtomTbl contains the atom table handle 
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prffiRE 


Function 


fsuccess = 
Wincreatecursor (hwnd, 
lx, ly, lcx, Icy, ulrgf, 
prclclip) 


hwndDlg = 
WincreateDIg 
(hwndparent, 
hwndowner, pDIgproc, 
pdlgtDlgTmp, 
pcreateparams) 


fsuccess = 
WincreateFramecontrols 
(hwndFrame, pFcdata, 
pszTitle) 


Description 


(NULLHANDLE indicates the call failed). ullnitial contains the 
initial size of the table in bytes. ulBuckets contains the size of 
the atom table hash table. Providing a value of 0 creates a hash 
table that uses the default size of 37. Always provide a prime 
number. 


The Wincreatecursor function creates or changes a text input 
cursor for a specified window. It automatically destroys any 
existing cursors. fsuccess contains true if this function is 
successful. hwnd contains the window handle. Ix contains the 
cursor X position. Iy contains the cursor Y position. lox contains 
the cursor X size 
the cursor Y size 


0 specifies a nominal cursor size). Icy contains 
0 specifies a nominal cursor size). ulrgf 


controls the cursor appearance. This includes: 
CURSOR_SOLID , CURSOR_HALFTONE, CURSOR_FRAME, 
CURSOR_FLASH, or CURSOR_SETPOS. prclclip contains 
the cursor rectangle coordinates. This is the area where the 
cursor is visible to the user. A NULL value uses the entire 
window area as the cursor clipping area. You can retrieve the 
last error using WinGetLastError. These errors include: 


Oxl001 PMERR INVALID HWND 
0xl019 PMERR-INVALID-FIAG 


The WincreateDlg function creates a dialog window. hwndDlg 
contains the dialog window handle (NULLHANDLE indicates an 
error). hwndparent contains the parent window handle: 
HWND_DESKTOP, HWND_OBJECT, or any other window 
handle. hwndowner contains the owner window handle. 
pDlgproc contains the dialog procedure for the dialog window. 
pdlgtDlgTmp contains a pointer to the dialog template. 
pcreateparams contains a pointer to the application data area. 
You can retrieve the last error using WinGetLastError. These 
errors include : 


Oxl001 PMERR INVALID HWND 
0xl015 PMERR-INVALID-ATOM NAME 
0xl016 PMERR-INVALID-INTEGER ATOM 
0xl017 PMERR-ATOM N-AME NOT-FOUND 


The WincreateFramecontrols function creates the standard 
frame controls for the specified window. fsuccess contains true 
if this function is successful. hwndFrame contains the frame 
window handle: HWND_DESKTOP, HWND_OBJECT, or any 
other window handle. pFcdata contains the frame control data 
(any combination of frame creation flags). pszTitle contains the 
title bar string. You can retrieve the last error using 
WinGetlrdstError. These errors include: 


Function 


hwndHelp = 
WincreateHelplnstance 
(hab, 
phinitHMlnitstructure) 


fsuccess = 
WincreateHelpTable 
(hwndHelplnstance, 
pthHelpTable) 


hwndMenu = 
WincreateMenu 
(hwndowner, 
pmtMenutmp) 


hmq= 
WincreateMsgQueue 
(hab, IQueuesize) 


hsuccess = 
Wincreateobject 
(pszclassName, 
pszTitle, pszsetupstring, 
pszLocation, ulFlags) 


Description 


Oxl001 PMERR INVALID HWND 
0xl019 PMERR-INVALID-FLAG 


The WincreateHelplnstance function creates an instance of the 
Help Manager. This allows you to request Help Manager 
functions. hwndHelp contains the Help Manager handle 
(NULLHANDLE indicates an error, the Help Manager returns 
the error code in the ulReturncode parameter of the HELPINIT 
structure). hab contains the anchor block handle. 
phinitHM I nitstructure contains the Help Manager initialization 
structure. 


The WincreateHelpTable function identifies or changes a help 
table. fsuccess contains true if this function is successful. 
hwndHelplnstance contains the Help Manager instance handle 
created using the WincreateHelplnstance function. 
pthHelpTable contains the help table allocated by the 
application. 


The WincreateMenu function creates a menu from the menu 
template. hwndMenu contains the menu window handle. 
hwndowner contains the owner and parent window handle: 
HWND_DESKTOP, HWND_OBJECT, or any other window 
handle. pmtMenutmp contains the menu template in binary 
format. You can retrieve the last error using WinGetLastError. 
These errors include: 


Oxl001 PMERR INVALID HWND 


The WincreateMsgQueue function creates a message queue. 
You must issue this call immediately after Winlnitialize, but 
before any Presentation Manager calls. Only issue this call once 
per thread. hmq contains the message queue handle 
(NULLHANDLE indicates an error). hab contains the anchor 
block handle. IQueuesize contains the maximum number of 
messages that you can queue. Providing a value of 0 uses the 
system default queue size. You can retrieve the last error using 
WinGetLastError. These errors include : 


Oxl00A PMERR RESOURCE NOT FOUND 
0xl011 PMERR-HEAP OUT-OF M-EMORY 
0xl012 PMERR-HEAP-MAX-SIZ-E REACHED 
0xl051 PMERR-NOT I-N A FM SESSION 
0x 1 052 PMERR=MSG=QOEUE_ALREADY_EXISTS 


The Wincreateobject function creates an instance of object 
class pszclassName. It uses a title pszTitle and places the icon 
and title in the location referred to by pszLocation. hsuccess 
contains the handle for the object (NULLHANDLE indicates an 
error). pszclassName contains the name of the object class. 
pszTitle contains the title that appears on the title when OS/2 
displays the object. pszsetupstring contains a pointer to a 
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Function 


hptr = 
Wincreatepointer 
(hwndDesktop, 
hbmBitMap, fpointersize 
lxHotspot, lyHotspot) 


Description 


setup string. pszLocation contains the location of the object as 
follows: "<WP_NOWHERE>" , "<WP_DESKTOP>" , 
"<WP_OS2SYS>" , "<WP_TEMPS>" , "<WP_CONFIG>" , 
``<WP_SIART>", ``<WP_INFO>", "<WP_DRIVES>", or a fully 


qualified path name. ulFlags contains the creation flags: 
CO FAILIFEXISTS or COREPLACEIFERISTS. The 
psz-Setupstring parameter contains the following keyr7ame = 
va/ue pairs. Each pair is separated by a comma. 


These values affect the behavior of the class. All parameters in 
this structure have safe defaults, you never need to pass 
unnecessary parameters. 


Keyname Valu e D e s criptio n 


TITLE Title Contains the object's title. 


ICON filename Contains the filename of the object's 


icon. 


HELPPANEL id 


TEM PLATE YES 


NO 


N ODELETE YES 


NO 


NOCOPY YES 


NO 


NOMOVE YES 


NO 


NOLINK YES 


NO 


Sets the object's default help panel. 


Sets the object's template property. 


Resets the object's template 
property. 
Sets the object's no delete property. 


Resets the object's no delete 
property. 
Sets the object's no copy property. 


Resets the object's no copy 
property. 
Sets the object's no move property. 


Resets the object's no move 
property. 
Sets the object's no link property. 


Resets the object's no link property. 


The Wincreatepointer function creates a pointer (either pointer 
or icon size) from a bitmap. hptr contains the pointer handle 
(NULLHANDLE indicates an error). hwndDesktop contains the 
desktop window handle (HWND_DESKTOP). hbmBitMap 
contains the bitmap handle. fpointersize contains the pointer 
size indicator: TRUE (stretch bitmap to conform to system 


Function 


hptr = 
Wincreatepointerlndirect 
(hwndDesktop, 
pptripointerlnfo) 


hwndFrame = 
Wincreatestdwindow 
(hwndparent, flstyle, 
pflcreateFlags, 
pszclassclient, pszTitle, 
flstyleclient, Besource, 
ulld, phwndclient) 


hswitchswitch = 
WincreateswitchEntry 
(hab, pswctlswitchData) 


Description 


pointer dimensions) or FALSE (stretch bitmap to conform to 
system icon dimensions). IXHotspot contains the X offset of the 
hotspot from the lower left corner in pels. IyHotspot contains 
the Y offset of the hotspot from the lower left corner in pels. 
You can retrieve the last error using WinGetLastError. These 
errors include : 


Oxl001 PMERR INVALID HWND 
0x2032 PMERR-HBITMAP BUSY 


The Wincreatepointer function creates a colored pointer (either 
pointer or icon size) from a bitmap. hptr contains the pointer 
handle (NULLHANDLE indicates an error). hwndDesktop 
contains the desktop window handle (HWND_DESKTOP). 
pptripointerl nfo contains the pointer information structure. This 
includes the following fields: ulpointer, xHotspot, yHotspot, 
hbmpointer, and hbmcolor. You can retrieve the last error 
using WinGetLastError. These errors include: 


Oxl001 PMERR INVALID HWND 
0x2032 PMERR-HBITMAP BUSY 


The Wincreatestdwindow function creates a standard window. 
hwndFrame contains the frame window handle 
(NULLHANDLE indicates an error). hwndparent contains the 
parent window handle. Use HWND_DESKTOP to create a 
main window. flstyle contains the frame window style. This 
includes any combination of Window Styles (WSs) and Frame 
Styles (FSs). pflcreateFlags contains the frame create flags. 
This includes any combination of Frame Creation Flags (FCFs). 
pszclassclient contains the client window class name. OS/2 
does not create a client area if pszclassclient is NULL. 
pszTitle contains the title bar text. flstyleclient contains the 
client window style. Besource contains a resource identifier 
(ignored unless you specify the FCF_MENU, FCF_STANDARD, 
FCF_ACCELTABLE, or FCF_ICON flags). NULLHANDLE 
indicates that the resources are contained in the application 
EXE file. ulld contains the frame window identifier. 
phwndclient contains the client window handle. You can 
retrieve the last error using WinGetLastError. These errors 
include: 


Oxl001 PMERR INVALID HWND 
0xl015 PMERR-INVALID-ATOM NAME 
0xl016 PMERR-INVALID-INTEGER ATOM 
0xl017 PMERR-ATOM N-AME NOT-FOUND 
0xl019 PMERR-INVALID FLAG 


The WincreateswitchEntry function adds an entry to the 
Window List. (This is the list of applications displayed to the 
user by the operating system.) hswitchswitch contains the 
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Function 


hwnd = 
Wincreatewindow 
(hwndparent, 
pszclassName, 
pszName, flstyle, 
lxcoord, lycoord, lwidth, 
lHeight, hwndowner, 
hwndBehind, id, 
pctlData, ppressparams) 


fsuccess = 
WinDdelnitiate 
(hwndclient, 
pszAppName, 
pszTopicName 
pcontext) 


fsuccess = 


Description 


Window List handle (NULLHANDLE indicates an error). 
pswctlswitchData contains information about the Window List 
entry. You can retrieve the last error using WinGetLastError. 
These errors include: 


Oxl201 PMERR NO SPACE 
0xl206 PMERR-INVALID WINDOW 
0xl20B PMERR-INVALID-SESSION ID 


The Wincreatewindow function creates a new window of class 
pszclassName and returns hwnd. hwnd contains the window 
handle (NULLHANDLE indicates an error). hwndparent 
contains the parent window handle. Use HWND_DESKTOP to 
create a main window. Use HWND_OBJECT or an object 
window handle to create an object window. pszclassName 
contains the registered class name. IVou can use a WC constant 
to define this parameter.) pszName contains the window text. It 
is class specific. flstyle contains the frame window style. This 
includes any combination of Window Styles (WSs) and Frame 
Styles (FSs). IxCoord contains the window X-coordinate position 
relative to the origin of the parent window. Iycoord contains 
the window Y-coordinate position relative to the origin of the 
parent window. Iwidth contains the width of the window in 
window coordinates. IHeight contains the height of the window 
in window coordinates. hwndowner contains the owner 
window handle. hwndBehind contains the sibling window 
handle, which includes: HWND_BOTTOM and HWND_TOP. 
You can retrieve the last error using WinGetLastError. These 
errors include : 


Oxl001 PMERR INVALID HWND 
0xl015 PMERR-INVALID-ATOM NAME 
0xl016 PMERR-INVALID-INTEGER ATOM 
0xl017 PMERR-ATOM N-AME NOT-FOUND 
Oxioi9 PMERR-INVALID FIAa 


The WinDdelnitiate function initiates a dynamic data exchange 
(DDE) conversation between a client and one or more other 
applications. It uses a national language conversation context. 
fsuccess contains true if this function is successful. hwndclient 
contains the client window handle. pszAppName contains the 
application name (the server name). A zero length string allows 
any application to respond. pszTopic contains the topic name. 
A zero length string allows the application to respond once for 
each topic it can support. pcontext contains the conversation 
context. 


The WinDdeRespond function allows an application to post a 


Function 


WinDdepostMsg 
(hwndTo, hwndFrom, 
usMsgld, pData, 
uloptions) 


mresBeply = 
WinDdeBespond 
(hwndclient, hwndserver, 
pszAppName, 
pszTopicName, 
pcontext) 


mresBeply = 
WinDefDlgproc 
(hwndDlg, ulMsgld, 
mpparaml , mpparam2) 


mresReply = 
WinDefFileDlgproc 
(hwndDlg, ulMsgld, 
mpparaml , mpparam2) 


mresBeply = 
WinDefFintDlgproc 
(hwndDlg, ulMsgld, 
mpparaml , mpparam2) 


mresReply = 
WinDefwindowproc 
(hwnd, ulMsgld, 
mpparaml , mpparam2) 


Description 


message to another application that it is carrying out a dynamic 
data exchange (DDE) conversation with using a national 
language conversation context. fsuccess contains true if this 
function is successful. hwndTo contains the target handle. 
hwndFrom contains the originator handle. usMsgld contains 
the message identifier, which includes: WM_DDE_ACK, 
WM_DDE_ADVISE , WM_DDE_DATA , WM_DDE_EXECUTE , 
WM_DDE_POKE , WM_DDE_REQUEST, 
WM_DDE_TERMINATE, and WM_DDE_UNADVISE. pData 
points to a DDE structure. You must always use a 16-bit address 
for this parameter. usoptions contains the DDE options, which 
include: DDEPM RETRY and DDEPM NOFREE. 


The WinDdeRespond function allows a dynamic data exchange 
(DDE) server to indicate that it can support a DDE conversation 
on a particular topic with a national language conversation 
context. mresBeply contains the message return information. 
hwndclient contains the client handle. hwndserver contains 
the server handle. pszAppName contains the application name 
(the server name). pszTopic contains the topic name. pcontext 
contains the conversation context. 


The WinDefDlgproc invokes the default dialog procedure. This 
provides a method of processing messages that the application 
does not wish to handle. mresBeply contains the message 
return data. hwndDlg contains the dialog window handle. 
ulMsgld contains the message identity. mpparaml contains 
the first parameter. mpparam2 contains the second parameter. 
You can retrieve the last error using WinGetLastError. These 
errors include: 


Oxl001 PMERR INVALID HWND 


The WinDefFileDlgproc function is the default dialog procedure 
for the file dialog. mresBeply contains the message return data 
hwndDlg contains the dialog window handle. ulMsgld contains 
the message identity. mpparaml contains the first parameter. 
mpparam2 contains the second parameter. 


The WinDefFontDlgproc function is the default dialog 
procedure for the font dialog. mresBeply contains the message 
return data. hwndDlg contains the dialog window handle. 
ulMsgld contains the message identity. mpparaml contains 
the first parameter. mpparam2 contains the second parameter. 


The WinDefwindowproc invokes the default window procedure. 
This provides a method of processing messages that the 
application does not wish to handle. mresBeply contains the 
message return data. hwnd contains the window handle. 
ulMsgld contains the message identity. mpparaml contains 
the first parameter. mpparam2 contains the second parameter. 
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Function 


hatomtblBeturncode 
WinDeleteAtom 
(hatomtblAtomTbl, 
atom) 


sltems = 
WinDeleteLboxltem 
(hwndLbox, slndex) 


fDeleted = 
WinDeleteLibrary (hab, 
hlibLibhandle) 


fsuccess = 
WinDeleteprocedure 
(hab, pwndproc) 


fsuccess = 
WinDeregisterobjectclass 
(pszclassName) 


fsuccess = 
WinDestroyAccelTable 
(haccelAccel) 


hatomtblpeturncode = 


Description 


You can retrieve the last error using WinGetLastError. These 
errors include : 


Oxl001 PMERR INVALID HWND 


The WinDeleteAtom function removes an atom from an atom 
table. If the atom has an atom name, its use count is 
decremented by one. The atom is removed from the table if its 
use count is zero. hatomtblBeturncode contains a zero for a 
successful completion. Any other value indicates an error. 
hatomtblAtomTbl contains the atom table handle. atom 
contains an identifier for the atom that you want to delete. You 
can retrieve the last error using WinGetLastError. These errors 
include: 


Oxl013 PMERR INVALID HATOMTBL 
0xl014 PMERR-INVALID-ATOM 


The WinDeleteLboxltem function removes an indexed item 
from a list box. sltems contains the number of items left. 
hwndLbox contains the listbox handle. slndex contains the 
index of the listbox item you want to remove. 


The WinDeleteLibrary function deletes a library that you 
previously loaded using the WinLoadLibrary function. fDeleted 
contains the library deletion indicator; TRUE indicates that 
OS/2 deleted the library. hab contains the anchor block handle. 
hlibLibhandle contains the library handle. 


The WinDeleteprocedure function deletes the window or dialog 
procedure that you previously loaded using the 
WinLoadprocedure function. fsuccess contains true if this 
function is successful. hab contains the anchor block handle. 
pwndproc contains the identifier of the window or dialog 
procedure that you want to delete. 
The WinDeregisterobjectclass function deregisters a workplace 
object class. fsuccess contains true if this function is successful. 
pszclassName contains the name of the class you want to 
deregister. 


The WinDestroyAccelTable function destroys an accelerator 
table. fsuccess contains true if this function is successful. 
haccelAccel contains the accelerator table handle. You can 
retrieve the last error using WinGetLastError. These errors 
include: 


Oxl01A PMERR INVALID HACCEL 


The WinDestroyAtomTable function destroys an atom table that 


Function 


WinDestroyAtomTable 
(hatomtblAtomTbl) 


fsuccess = 
WinDestroycursor 
(hwnd) 


fsuccess = 
WinDestroyHelplnstance 
(hwndHelplnstance) 


f Destroyed = 
WinDestroyMsgQueue 
(hmq) 


fsuccess = 
WinDestoryobject 
(hobject) 
fsuccess = 
WinDestroypointer 
(hptrpointer) 


fsuccess = 
WinDestroywindow 
(hwnd) 


fsuccess = 


Description 


you created using the WincreateAtomTable function. OS/2 will 
not allow you to destroy the system atom table. 
hatomtblBeturncode contains a zero for a successful 
completion. Any other value indicates an error. 
hatomtblAtomTbl contains the atom table handle. You can 
retrieve the last error using WinGetLastError. These errors 
include: 


Oxl013 PMERR INVALID HATOMTBL 


The WinDestroycursor function destroys the current cursor if it 
belongs to the specified window. fsuccess contains true if this 
function is successful. hwnd contains the window handle. You 
can retrieve the last error using WinGetLastError. These errors 
include: 


Oxl001 PMERR INVALID HWND 


The WinDestroyHelplnstance function destroys the specified 
help instance of the Help Manager. fsuccess contains true if 
this function is successful. hwndHelplnstance contains the 
handle of the instance of the Help Manager that you want to 
destroy. 


The WinDestroyMsgQueue function destroys a message queue. 
Always call this function before you terminate a thread or 
application that uses a message queue. fDestroyed contains 
true if this function is successful. hmq contains the message 
queue handle. You can retrieve the last error using 
WinGetLastError. These errors include : 


Oxl002 PMERR_INVALID_HMQ 


The WinDestroyobject function destroys a workplace object. 
fsuccess contains true if this function is successful. hobject 
contains the object handle. 


The WinDestroypointer function destroys a pointer or icon. 
Never attempt to destroy the system icons or pointers. 
fsuccess contains true if this function is successful. hptrpointer 
contains the handle of the pointer or icon that you want to 
destroy. You can retrieve the last error using WinGetLastError. 
These errors include: 


Oxl01B PMERR INVALID HPTR 


The WinDestroywindow function destroys a window and its 
children. fsuccess contains true if this function is successful. 
hwnd contains the window handle. You can retrieve the last 
error using WinGetLastError. These errors include: 


Oxl001 PMERR INVALID HWND 


The WinDismissDlg function hides a modal dialog window or 
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Function 


WinDismissDlg 
(hwndDlg, ulBesult) 


mresReply = 
WinDispatchMsg 
(hab, pqmsgMsg) 


ulResult = 
WinDlgBox (hwndparent, 
hwndowner, pDlgproc, 
Besource, ulDlgld, 
pcreateparams) 


fsuccess = 
WinDrawBitmap (hps, 
hbm, prclsrc, pptlDest 
lForecolor, lBackcolor, 
flBgf) 


Description 


destroys a modal dialog window. This causes the WinprocessDlg 
and WinDlgBox functions to return. fsuccess contains true if 
this function is successful. hwndDlg contains the dialog window 
handle. ulBesult contains the reply value returned to the caller 
of the WinprocessDlg or WinDlgBox functions. You can retrieve 
the last error using WinGetLastError. These errors include: 


Oxl001 PMERR INVALID HWND 


The WinDispatchMsg function invokes a window procedure. 
mresBeply contains the message reply data. hab contains the 
anchor block handle. pqmsgMsg contains the message 
structure. 


The WinDlgBox function loads and processes a modal dialog 
box window. It returns the result value established by the 
WinDismissDlg call. ulBesult contains the reply value 
(DID_ERROR indicates an error). hwndparent contains the 
parent window handle: HWND_DESKTOP, HWND_OBJECT, 
or other specified window. hwndowner contains the handle of 
the actual window owner. pDlgproc contains a pointer to the 
procedure for the created dialog window. Besource contains 
the resource identity containing the dialog template 
(NULLHANDLE uses the application's EXE file). ulDlgid 
contains the dialog template identity within the resource file. 
pcreateparams contains the application defined data area. You 
can retrieve the last error using WinGetLastError. These errors 
include: 


Oxl001 PMERR INVALID HWND 
0xl00A PMERR-RESOUR-CE NOT FOUND 
0xl015 PMERR-INVALID AT-OM N-AME 
0xl016 PMERR-INVALID-INTEGER ATOM 
0xl017 PMERR-ATOM N-AME NOT-FOUND 
The WinDrawBitmap function draws a bitmap using the current 
image colors and mixes. fsuccess contains true if this function 
is successful. hps contains the presentation space handle. hbm 
contains the bitmap handle. prclsrc contains the subrectangle 
of the bitmap to draw. Use a value of NULL to draw the entire 
bitmap. pptlDest contains the bitmap destination in device 
coordinates. IForecolor contains the foreground color of a 
monochrome bitmap (color bitmap colors are not changed). 
IBackcolor contains the bitmap background color. flBgf 
contains the flags that determine how OS/2 draws the bitmap. 
These flags include: DBM_NORMAL, DBM_INVERT, 
DBM_STRETCH, DBM_HALFTONE, and 
DBM_IMAGEAITRS. You can retrieve the last error using 
WinGetLastError. These errors include: 


Function 


fsuccess = 
WinDrawBorder (hps, 
prclBectangle, 
lvertsidewidth, 
lHorizsidewidth, 
lBordercolor, 
llnteriorcolor, flcmd) 


fsuccess = 
WinDrawpointer (hps, 
lx, lY, hptrpointer, 
ulHalftone) 


lchars = 
WinDrawText (hps, 
lcount, pchText, 
prclBectangle, 
lForecolor, lBackcolor, 
flcmd) 


Description 


Oxl019 PMERR INVALID FLAG 
0x2032 PMERR-HBITMAP BUSY 


The WinDrawBorder function draws the borders and interior of 
a rectangle. fsuccess contains true if this function is successful. 
hps contains the presentation space handle. prclBectangle 
contains the bounding rectangle for the border in device 
coordinates. Ivertsidewidth contains the width of the border's 
vertical sides in device coordinates. IHorizsidewidth contains 
the width of the border's horizontal sides in device coordinates. 
IBordercolor contains the color of the edge border. 
Ilnteriorcolor contains the color of the interior border. flcmd 
contains a list of flags that control how OS/2 draws the border. 
These flags include: DB_PATCOPY, DB_PATINVERT, 
DB_DESTINVERT, or DB_AREAMIXMODE. Only one of these 
flags is significant. Other flags include: DB_ROP, 
DB_INTERIOR, DB_AREAAITRS, DB_STANDARD , and 
DB_DLGBORDER. You can retrieve the last error using 
WinGetLastError. These errors include: 


Oxl019 PMERR INVALID FLAG 
0x2068 PMERR-INVALID-DRAW BORDER OPTION 


The WinDrawpointer function draws a pointer. fsuccess 
contains true if this function is successful. hps contains the 
presentation space handle. IX contains the pointer X 
coordinate. IY contains the pointer Y coordinate. hptrpointer 
contains the pointer handle. ulHalftone controls the pointer 
shading. This includes: DP_NORMAL, DP_HALFTONED, and 
DP_INVERTED. You can retrieve the last error using 
WinGetLastError. These errors include : 


Oxl019 PMERR INVALID FLAG 
0xl01B PMERR-INVALID-HPTR 


The WinDrawText function draws a single line of formatted 
(using the current font and colors) text within the specified 
rectangle. Ichars contains the number of characters drawn 
within the rectangle (0 indicates an error). hps contains the 
presentation space handle. ICount contains the number of 
characters in the string (use -1 for a null-terminated string). 
pchText is a pointer to the string. prclBectangle contains the 
text bounding rectangle in world coordinates. IForecolor 
contains the foreground color. IBackcolor contains the 
background color. flcmd is an array of flags that determine how 
OS/2 draws the text. There are three groups of mutually 
exclusive flags. The first group includes: DT_LEFT, 
DT_CENTER, and DT_RIGHT. The second group includes: 


Table 3-43 Continued 


Function 


fsuccess = 
WinEmptyclipbrd 
(hab) 
fsuccess = 
WinEnablecontrol 
(hwndDlg, usld, fEnable) 


fsuccess = 
WinEnableMenultem 
(hwndMenu, usld, 
fEnable) 


foldlnputstate = 
WinEnablephyslnput 
(hwndDesktop, 
fNewlnputstate) 


fsuccess = 
WinEnablewindow 
(hwnd, fNewEnabled) 


fsuccess = 
WinEnablewindowupdate 
(hwnd, fNewvisibility) 


Description 


DT_TOP, DT_VCENTER, and DT_BOTTOM. The third group 
includes : DT_HALFTONE, DT_ERASERECT, and 
DT_MNEMONIC. You can retrieve the last error using 
WinGetLastError. These errors include : 


Oxl019 PMERR INVALID FLAG 


The WinEmptyclipboard function empties the clipboard of all 
handles to data. fsuccess contains true if this function is 
successful. hab contains the anchor block handle. 


The WinEnablecontrol function sets the enable flag of the 
specified item in the dialog template. fsuccess contains true if 
this function is successful. hwndDlg contains the dialog window 
handle. usld contains the identify of the item. fEnable contains 
the enable flag. 


The WinEnableMenultem function sets the enable flag of the 
specified item in the menu. fsuccess contains true if this 
function is successful. hwndMenu contains the menu window 
handle. usld contains the identity of the item. fEnable contains 
the enable flag. 


The WinEnablephyslnput function enables or disables queuing 
of physical input (mouse or keyboard). fold I nputstate contains 
the previous state. TRUE indicates that the device and keyboard 
input are queued. hwndDesktop contains the desktop window 
handle (HWND_DESKTOP in most cases). fNewl nputstate 
contains the new state for queuing physical input. You can 
retrieve the last error using WinGetLastError. These errors 
include: 


Oxl001 PMERR INVALID HWND 


The WinEnablewindow function sets the window enabled state. 
fsuccess contains true if this function is successful. hwnd 
contains the window handle. fNewEnabled contains the enable 
flag. You can retrieve the last error using WinGetLastError. 
These errors include: 


Oxl001 PMERR INVALID HWND 


The WinEnablewindowupdate function sets the window 
visibility state for subsequent drawing. It does not cause any 
change to the window on the device. fsuccess contains true if 
this function is successful. hwnd contains the window handle. 
fNewvisibility contains the enable flag. You can retrieve the last 
error using WinGetLastError. These errors include: 


Oxl001 PMERR INVALID HWND 


Function 


fsuccess = 
WinEndEnumwindows 
(henum) 


fsuccess = 
WinEndpaint (hps) 


ulNext = 
WinEnumclipbrdFmts 
(hab, ulprev) 


hwndltem = 
WinEnumDlgltem 
(hwndDlg, hwnd, 
ulcode, fLock) 


fsuccess = 
WinEnumobjectclasses 
(pobjclass, psize) 


fEqual = 
WinEqualBect (hab, 
prclBectl , prclpect2) 


lcomplexity = 


Description 


Oxl019 PMERR INVALID FIAG 


The WinEndEnumwindows function ends the enumeration 
process for a specified enumeration. fsuccess contains true if 
this function is successful. henum contains the enumeration 
handle. You can retrieve the last error using WinGetLastError. 
These errors include: 


Oxl01C PMERR INVALID HENUM 


The WinEndpaint function completes the redrawing of a 
window. (It normally appears as a part of WM_PAINT message 
processing.) fsuccess contains true if this function is successful. 
hps contains the presentation space handle. 


The WinEnumclipbrdFmts function enumerates the list of 
available clipboard data formats. ulNext contains the next 
clipboard data index (0 indicates that enumeration is complete). 
hab contains the anchor block handle. ulprev contains the 
previous clipboard data format index (always start at 0). 
The WinEnumDlgltem returns the window handle of a dialog 
item within a dialog window. hwndltem contains the item 
handle. hwndDlg contains the dialog window handle. hwnd 
contains the child window handle. You can use a value of 
NULLHANDLE if ulcode is EDI FIRSTTABITEM or 
EDI_LASTIABITEM. ulcode co=tains the item type code, 
which includes: EDI_PREVTABITEM , EDI_NEXIABITEM , 
EDI_FIRSTTABITEM , EDI_LASTTABITEM , 
EDI_PREVGROUPITEM , EDI_NEXTGROUPITEM , 
EDI_FIRSTGROUPITEM, or EDI_FIRSTGROUPITEM. fLock 
contains the lock indicator. OS/2 versions 1.2 and above ignore 
this parameter. You can retrieve the last error using 
WinGetLastError. These errors include : 


Oxl001 PMERR INVALID HWND 


The WinEnumobjectclasses function returns a list of all the 
registered workplace object classes. fsuccess contains true if 
this function is successful. pobjclass contains a pointer to the 
buffer used to store the object class list. psize contains the 
length of pobjclass in bytes. 


The WinEqualRect function compares two rectangles for 
equality. (OS/2 considers two empty rectangles equal even 
though their coordinate values are different.) fEqual contains 
true if the two rectangles are equal. hab contains the anchor 
block handle. prclBectl contains the coordinates of the first 
rectangle. prclBect2 contains the coordinates of the second 
rectangle. 


The WinExcludeupdateRegion function subtracts the update 


Table 3-43 Continued 


Function 


WinExcludeupdate- 
Begion (hps, hwnd) 


hwndDlg = 
WinFileDlg (hwndparent, 
hwndowner, pfFiledlg) 


fsuccess = 
WinFillBect (hps 
prclBect, lcolor) 


atom = 
WinFindAtom 
(hatomtblAtomTbl 
pszAtomName) 


fsuccess = 


Description 


region of a window from the clipping region of a presentation 
space. IComplexity contains the complexity of the resulting 
region or an error indicator. hps contains a presentation space 
handle. hwnd contains the window handle. 
WinExcludeupdateRegion returns one of the following values: 


0000 EXRGN ERROR 
0001 EXRGN-NULL 
0002 EXRGN-RECT 
0003 EXRGN-COMPLEX 


You can retrieve the last error using WinGetLastError. These 
errors include: 


Oxl001 PMERR INVALID HWND 


The WinFileDlg function creates and displays the file dialog box 
and returns the user's selections. hwndDlg contains the file 
dialog window handle. If the FDS_MODELESS flag is set, then 
the return value is the handle of the file dialog NULLHANDLE 
indicates that OS/2 cannot create the dialog. If the 
FDS_MODELESS flag is not set, then the return value is TRUE 
for successful creation (NULLHANDLE indicates an unsuccessful 
attempt). hwndparent contains the parent window handle 
(HWND_DESKTOP or other specified window). hwndowner 
contains the owner window handle. pfFiledlg contains a pointer 
to FILEDLG structure. 


The WinFillRect function draws a filled rectangular area. 
fsuccess contains true if this function is successful. hps 
contains the presentation space handle. prclBect contains the 
coordinates in world coordinates of the rectangle that you want 
to fill. IColor contains the color that you want to use to fill the 
rectangle. You can use either a color index or an RGB color 
value. 


The WinFindAtom function finds an atom in the atom table. 
atom contains the atom value (0 indicates an invalid atom table 
handle or name specified). hatomtblAtomTbl contains the atom 
table handle. pszAtomName contains the atom name. You can 
retrieve the last error using WinGetLastError. These errors 
include: 


Oxl013 PMERR INVALID HATOMTBL 
0xl015 PMERR-INVALID-ATOM NAME 
0xl 016 PMERR-INVALID-INTEGER_ATOM 
0xl017 PMERR-ATOM N-AME NOT_FOUND 


The WinFlashwindow function starts or stops window flashing. 


Function 


WinFlashwindow 
(hwnd, fFlash) 


fsuccess = 
WinFocuschange 
(hwndDesktop, 
hwndNewFocus, 
flFocuschange) 


hwndDlg = 
WinFontDlg (hwndparent, 
hwndowner, 
pfntdFontdlg) 


fsuccess = 
WinFreeErrorlnfo 
(perriErrorlnfo) 


fsuccess = 
WinFreeFileDlgList 
(papszFQFilename) 


fsuccess = 
WinFreeFilelcon (hptr) 


hps = WinGetclipps 


Description 


fsuccess contains true if this function is successful. hwnd 
contains the window handle. fFlash contains the flashing 
indicator; a value of TRUE starts window flashing. You can 
retrieve the last error using WinGetLastError. These errors 
include: 


Oxl001 PMERR INVALID HWND 


The WinFocuschange function changes the focus window. 
fsuccess contains true if this function is successful. 
hwndDesktop contains the desktop window handle 
(HWND_DESKTOP or other desktop window handle). 
hwndNewFocus contains the handle of the window that will 
receive focus. flFocuschange contains the focus change 
indicator. This includes: FC_NOSETFOCUS, 
FC_NOLOSEFOCUS , FC_NOSETACTIVE, 
FC_NOLOSEACTIVE, FC_NOSETSELECTION , 
FC_NOBRINGTOTOP, FC_NOBRINGTOTOPFIRSTWINDOW, 
and FC SETACTIVEFOCUS. You can retrieve the last error 
using W-inGetLastError. These errors include: 


Oxl001 PMERR INVALID HWND 


The WinFontDlg function creates and displays the font dialog 
box and returns the user's selections. hwndDlg contains the 
font dialog window handle. If the FNTS_MODELESS flag is set, 
then the return value is the handle of the file dialog 
(NULLHANDLE indicates that OS/2 cannot create the dialog). 
If the FNTS_MODELESS flag is not set, then the return value is 
TRUE for successful creation (NULLHANDLE indicates an 
unsuccessful attempt). hwndparent contains the parent window 
handle (HWND_DESKTOP or other specified window). 
hwndowner contains the owner window handle. pfntdFiledlg 
contains a pointer to FILEDLG structure. 


The WinFreeErrorlnfo function releases memory allocated for 
an error information block. fsuccess contains true if this 
function is successful. perriErrorlnfo contains a pointer to the 
error information block. 


The WinFreeFileDlgList function frees the storage allocated by 
the file dialog when the FDS_MULTPLESEL flag is set. 
fsuccess contains true if this function is successful. 
papszFQFilename contains a pointer to a table of pointers to 
fully qualified filename returned by the dialog. 


The WinFreeFilelcon function frees the pointer to an icon 
allocated by the WinLoadFilelcon function. fsuccess contains 
true if this function is successful. hptr contains the pointer 
handle. 


The WinGetclipps function obtains a clipped cache 
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Function 


(hwnd, hwndclipwindow, 
ulclipflags) 


ulTime = 
WinGetcurrentTime 
(hab) 


fF3esult = 
WinGetDlgMsg 
(hwndDlg, pqmsgMsg) 


perriErrorlnfo = 
WinGetErrorlnfo (hab) 


lKeystate = 
WinGetKeystate 
(hwndDesktop, lvk) 


erridErrorcode = 


Description 


presentation space. hps contains the presentation space 
handle. hwnd contains the window handle. hwndclipwindow 
contains the handle of the window used for clipping. You can 
specify one of the following values: HWND_BOTroM, 
HWND_TOP, or NULLHANDLE. ulclipflags contains the 
clipping control flags, which include: PSF_CLIPSIBLINGS, 
PSF_CLIPCHILDREN , PSF_CLIPUPWARDS , 
PSF_CLIPDOWNWARDS , PSF_LOCKWINDOWUPDATE, and 
PSF_PARENTCLIP. You can retrieve the last error using 
WinGetLastError. These errors include : 


Oxl001 PMERR INVALID HWND 


The WinGetcurrentTime function returns the current time. 
ulTime contains the system time count in milliseconds from the 
system Initial Program Load (IPL). hab contains the anchor 
block handle. 


The WinGetDlgMsg function gets a message from the 
application queue associated with the specified dialog. fBesult 
contains TRUE if the message returned is not a WM_QUIT 
message and the dialog was not dismissed. hwndDlg contains 
the dialog window handle. pqmsgMsg contains a pointer to the 
message structure. You can retrieve the last error using 
WinGetLastError. These errors include : 


Oxl001 PMERR INVALID HWND 


The WinGetErrorlnfo function returns detailed error 
information. (The memory allocated by this function is not 
released until you call the WinFreeErrorlnfo function.) 
perriErrorlnfo contains a pointer to the error information 
structure (NULL if no error information is available). hab 
contains the anchor block handle. 


The WinGetKeystate function returns the state of the key at the 
time that the last message from the queue was posted. 
IKeystate cohtains the key state. It is an OR combination of the 
following values: OxOOO1 (the key was pressed an odd number 
of times since the system started) and Ox8000 (the key is down). 
hwndDesktop contains the desktop window handle 
(HWND_DESKTOP or other desktop window handle). Ivk 
contains the virtual key value in the low-order byte and zero in 
the high-order byte. You can retrieve the last error using 
WinGetLastError. These errors include : 


Oxl001 PMERR INVALID HWND 


The WinGetLastError function returns the error state set by the 


Function 


WinGetLastError (hab) 


fsuccess = 
WinG6tMaxposition 
(hwnd, pSwp) 


fsuccess = 
WinGetMinposition 
(hwnd, pSwp, pptlpoint) 


fResult = 
WinGetMsg (hab, 
pqmsgMsg, hwndFilter, 
ulFirst, ulLast) 


hwndNext = 
WinGetNextwindow 
(henum) 


lKeystate = 
WinGetphysKeystate 
(hwndDesktop, 
lscancode) 


hps = WinGetps (hwnd) 


Description 


failure of a PM function. It automatically sets the error code to 
zero. erridErrorcode contains the last error state. hab contains 
the anchor block handle. 


The WinGetMaxposition function fills an SWP structure with the 
maximized window size and position. fsuccess contains true if 
this function is successful. hwnd contains the frame window 
handle. pSwp contains a pointer to the SWP structure. 


The WinGetMinposition function fills an SWP structure with the 
minimized window size and position. fsuccess contains true if 
this function is successful. hwnd contains the frame window 
handle. pSwp contains a pointer to the SWP structure. 
pptlpoint contains the preferred position. Use NULL if you 
want the system to choose the position. 


The WinGetMsg function gets a message from the thread's 
message queue. It waits until a message that conforms to the 
filtering criteria is available. fBesult returns TRUE if the 
message returned is not a WM_QUIT message. hab contains 
the anchor block handle. pqmsgMsg contains a pointer to the 
message structure. hwndFilter contains the filter window 
handle. ulFirst contains the first message identity. ulLast 
contains the last message identity. You can retrieve the last 
error using WinGetLastError. These errors include: 


Oxl001 PMERR INVALID HWND 


The WinGetNextwindow function gets the handle of the next 
window in an enumeration list. hwndNext contains the handle 
of the next window in the enumeration list (NULLHANDLE 
indicates an error). henum contains the enumeration handle. 
You can retrieve the last error using WinGetLastError. These 
errors include : 


Oxl01C PMERR INVALID HENUM 


The WinGetphysKeystate function returns the physical key 
state. IKeystate contains the key state. It is an OR combination 
of the following values: OxOOO1 (the key was pressed an odd 
number of times since the system started), Ox0002 (the key was 
pressed since the last time the application called this function), 
and Ox8000 (the key is down). hwndDesktop contains the 
desktop window handle (HWND_DESKTOP or other desktop 
window handle). IScancode contains the hardware key value in 
the low-order byte and zero in the high-order byte. You can 
retrieve the last error using WinGetLastError. These errors 
include: 


Oxl001 PMERR INVALID HWND 


The WinGetps function returns the handle to a cache 
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Function 


hpsscreenps = 
WinGetscreenps 
(hwndDesktop) 


hbm= 
WinGetsysBitmap 
(hwndDesktop, ullndex) 


Description 


presentation space. hps contains the presentation space handle. 
hwnd contains the window handle (HWND_DESKTOP or other 
window handle). You can retrieve the last error using 
WinGetLastError. These errors include : 


Oxl001 PMERR INVALID HWND 


The WinGetscreenps function returns a handle to a 
presentation space that you can use for drawing anywhere on 
the display. As a result, you must exercise extreme caution not 
to draw on the windows of other applications when using this 
function. hpsscreenps contains the presentation space handle 
(NULLHANDLE indicates an error). hwndDesktop contains the 
desktop window handle (HWND_DESKTOP or other desktop 
window handle). You can retrieve the last error using 
WinGetLastError. These errors include: 


Oxl001 PMERR INVALID HWND 


The WinGetsysBitmap function returns a handle to one of the 
standard bitmaps provided by the system. You can use this 
bitmap for any normal bitmap operation; it is a copy of the 
original system bitmap. hbm contains the bitmap handle 
(NULLHANDLE indicates an error). hwndDesktop contains the 
desktop window handle (HWND_DESKTOP or other desktop 
window handle). ullndex contains the system bitmap index 
value, which includes: SBMP_SYSMENU, 
SBMP_SYSMENUDEP, SBMP_SBUPARROW, 
SBMP_SBUPARROWDEP, SBMP_SBUPARROWDIS , 
SBMP_SBDNARROW, SBMP_SBDNARROWDEP, 
SBMP_SBDNARROWDIS , SBMP_SBRGARROW, 
SBMP_SBRGARROWDEP, SBMP_SBRGARROWDIS , 
SBMP_SBLFARROW, SBMP_SBLFARROWDEP, 
SBMP_SBLFARROWDIS, SBMP_MENUCHECK, 
SBMP_MENUATTACHED , SBMP_CHECKBOXES , 
SBMP_COMBODOWN , SBMP_BTNCORNERS, 
SBMP_MINBUITON , SBMP_MINBUITONDEP, 
SBMP_MAXBUITON , SBMP_MAXBUITONDEP, 
SBMP_RESTOREBUTTON , SBMP_RESTOREBUITONDEP, 
SBMP_CHILDSYSMENU , SBMP_CHILDSYSMENUDEP, 
SBMP_DRIVE, SBMP_FILE, SBMP_FOLDER, 
SBMP_TREEPLUS , SBMP_TREEMINUS , 
SBMP_CLOSEBUITON , SBMP_CLOSEBUITONDEP, 
SBMP_PROGRAM, and SBMP_SIZEBOX. You can retrieve the 
last error using WinGetLastError. These errors include: 


Oxl001 PMERR INVALID HWND 
0xl003 PMERR-PARAME-TER OUT OF RANGE 
0xl00A PMERR-RESOURCE NOT IOU-ND 


Function 
fsuccess = 
WinlnflateBect (hab 
prclBect, lcx, ICY) 


hab = Winlnitialize 
(floptions) 


fprocessing = 
WinlnsendMsg (hab) 


sF3etlndex = 
WinlnsertLboxltem 
(hwndLbox, slndex, 
pszText) 


fsuccess = 
WinlntersectBect 
(hab, prclDest, 
prclBectl , prclBect2) 


fsuccess = 
WinlnvalidateBect 
(hwnd, prclprc, 
flncludeclippedchildren) 


WinlnvalidateBegion 


Description 


The WinlnflateRect expands or contracts a rectangle. fsuccess 
contains true if this function is successful. hab contains the 
anchor block handle. prclBect contains the coordinates of the 
rectangle that you want to expand. lox contains the horizontal 
expansion factor. ICY contains the vertical expansion factor. 


The Winlnitialize function initializes the PM facilities. You must 
issue this call prior to any other PM call. hab contains the 
anchor block handle (NULLHANDLE indicates an error). 
floptions contains the initialization options (0 is the only 
available option). 


The WinlnsendMsg function determines whether the current 
thread is processing a message sent by another thread. 
fprocessing contains the message processing indicator. TRUE 
indicates that the current thread is processing a message sent by 
another thread. hab contains the anchor block handle. 


The WinlnsertLboxltem inserts text into a list box at the 
specified index. spetlndex contains the actual index where the 
text got inserted. hwndLbox contains the list box handle. 
slndex contains the index of the list box item. pszText contains 
the text that you want to insert. 


The WinlntersectRect function calculates the intersection of two 
rectangles and places the result in the destination rectangle. If 
there is no intersection, OS/2 returns an empty rectangle. 
fsuccess contains true if this function is successful. hab 
contains the anchor block handle. prclDest contains the 
intersection of prclBectl and prclBect2. prclBectl and 
prclBect2 contain the two rectangles that you want to intersect. 
The WinlnvalidateRect function adds a rectangle to a window's 
update region. This makes the region within the rectangle 
invalid; that area of the window requires redrawing. fsuccess 
contains true if this function is successful. hwnd contains the 
window handle (HWND_DESKTOP or other window handle). 
prclprc contains the update rectangle coordinates. A value of 
NULL updates the entire window. flncludeclippedchildren 
contains the invalidation scope indicator. A value of TRUE 
includes the children of hwnd in the update. You can retrieve 
the last error using WinGetLastError. These errors include: 


Oxl001 PMERR INVALID HWND 
0xl019 PMERR-INVALID-FLAG 


The WinlnvalidateRegion function adds a region to the 
window's update region. This makes the region invalid; that 
area of the window requires redrawing. fsuccess contains true 
if this function is successful. hwnd contains the window handle 
(HWND_DESKTOP or other window handle). hrgn contains the 
handle of the region that you want to add to the window. A value 
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Function 


fsuccess = 
WinlnvertBect (hps, 
prclBect) 


f Related = 
Winlschild (hwndchild, 
hwndparent) 


fsuccess = 
WinlscontrolEnabled 
(hwndDlg, usld) 


fsuccess = 
WinlsMenultemchecked 
(hwndMenu, usld) 


fsuccess = 
WinlsMenultemEnabled 
(hwndMenu, usld) 


fsuccess = 
WinlsMenultemvalid 
(hwndMenu, usld) 


fsuccess = 
WinlsphyslnputEnabled 
(hwndDesktop) 


Description 


of NULLHANDLE updates the entire window. 
flncludeclippedchildren contains the invalidation scope 
indicator. A value of TRUE includes the children of hwnd in the 
update. You can retrieve the last error using WinGetLastError. 
These errors include: 


Oxl001 PMERR INVALID HWND 
0xl019 PMERR-INVALID-FIAG 
0x2034 PMERR-HRGN B-USY 


The WinlnvertRect function inverts a rectangular area. This 
essentially flips the bits of each pel (logical NOT operation). 
fsuccess contains true if this function is successful. hps 
contains the presentation space handle. prclBect contains the 
coordinates of the rectangle that you want to invert. 


The Winlschild function tests whether one window is a child of 
another window. fBelated contains TRUE if the child window is 
a descendent of the parent window. hwndchild contains the 
handle of the child window. hwndparent contains the handle of 
the parent window. You can retrieve the last error using 
WinGetLastError. These errors include: 


Oxl001 PMERR INVALID HWND 


The WinlscontrolEnabled function returns the state of the 
specified item in the dialog template within a dialog box. 
fsuccess contains true if this function is successful. hwndDlg 
contains the dialog window handle. usld contains the item 
identifier. 


The WinlsMenuchecked function returns the state of the 
specified item in the menu. fsuccess contains true if this 
function is successful. hwndMenu contains the menu window 
handle. usld contains the item identifier. 


The WinlsMenuEnabled function returns the state of the 
specified item in the menu. fsuccess contains true if this 
function is successful. hwndMenu contains the menu window 
handle. usld contains the item identifier. 


The WinlsMenultemvalid function returns true if the specified 
menu item is valid. fsuccess contains true if this function is 
successful. hwndMenu contains the menu window handle. usld 
contains the item identifier. 


The WinlspkyslnputEnabled function returns the hardware input 
status. fsuccess contains true if this function is successful. 
hwndDesktop contains the desktop window handle 
(HWND_DESKTOP). 


Function 


fEmpty = 
WinlsBectEmpty 
(hab, prclprc) 


fActive = 
WinlsThreadActive (hab) 


fvalid = Winlswindow 
(hab, hwnd) 


fEnabled = 
WinlswindowEnabled 
(hwnd) 


fshowing = 
Winlswindowshowing 
(hwnd) 


fvisible = 
Winlswindowvisible 
(hwnd) 


haccelAccel = 
WinLoadAccelTable 
(hab, Besource, 
idAccelTable) 


Description 


The WinlsRectEmpty function checks whether a rectangle is 
empty. fEmpty contains TRUE if the rectangle is empty. hab 
contains the anchor block handle. prclprc contains the 
coordinates of the rectangle to check. 


The WinlsThreadActive function determines if the active 
window belongs to the calling execution thread. fActive 
contains TRUE if the active window belongs to the calling 
thread. hab contains the anchor block handle. 


The Winlswindow function determines if a window handle is 
valid. fvalid returns true if the window handle is valid. hab 
contains the anchor block handle. hwnd contains the window 
handle. You can retrieve the last error using WinGetLastError. 
These errors include: 


Oxl001 PMERR INVALID HWND 


The WinlswindowEnabled function determines the 
enabled/disabled state of a window. fEnabled contains TRUE if 
the window is enabled. hwnd contains the window handle. You 
can retrieve the last error using WinGetLastError. These errors 
include: 


Oxl001 PMERR INVALID HWND 


The Winlswindowshowing function determines if any part of 
the window is visible. fshowing contains TRUE if some part of 
the window is visible. hwnd contains the window handle. You 
can retrieve the last error using WinGetLastError. These errors 
include: 


Oxl001 PMERR INVALID HWND 


The Winlswindowvisible function returns the visibility state of a 
window. (This function only returns the status of the 
WS_VISIBLE style bits; it does not determine if a window is 
obscured by other windows.) fvisible contains TRUE if the 
window and all its parents have the WS_VISIBLE style bit set 
on. hwnd contains the window handle. You can retrieve the last 
error using WinGetLastError. These errors include: 


Oxl001 PMERR INVALID HWND 


The WinLoadAccelTable loads an accelerator table. 
haccelAccel contains the accelerator table handle. hab 
contains the anchor block handle. Besource contains the 
resource identity containing the accelerator table. 
NULLHANDLE indicates the application module contains the 
accelerator table. idAccelTable contains the accelerator table 
identifier within the resource file. You can retrieve the last error 
using WinGetLastError. These errors include: 


Oxl00A PMERR RESOURCE NOT FOUND 
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Function 


hwndDlg = 
WinLoadDIg 
(hwndparent, 
hwndowner, pDlgproc, 
Besource, idDlgid, 
pcreateparams) 


hptrsuccess = 
WinLoadFilelcon 
(pszFilename, fprivate) 


fsuccess = 
WinLoadHelpTable 
(hwndHelplnstance, 
idHelpTable, hModule) 


hlibLibrary = 
WinLoadLibrary 
(hab, pszLibname) 


hwndMenu = 
WinLoadMenu 
(hwndowner, Besource, 
idMenuid) 


Description 


The WinLoadDlg function creates a dialog window from a 
dialog template. hwndDlg contains the dialog window handle 
(NULL indicates the the dialog was not created). hwndparent 
contains the parent window handle: HWND_DESKTOP, 
HWND_OBJECT, or any other window handle. hwndowner 
contains the owner window handle. pDlgproc contains the 
dialog procedure for the dialog window. pDlgproc contains a 
pointer to the dialog template. Besource contains the identity 
of the resource containing the dialog template. A value of 
NULLHANDLE indicates the template is in the application's 
EXE file. idDlgid contains the dialog template identity. 
pcreateparams contains a pointer to the application data area. 
You can retrieve the last error using WinGetlrdstError. These 
errors include: 


Oxl001 PMERR INVALID HWND 
0xl00A PMERR-RESOUR-CE NOT FOUND 
0xl015 PMERR-INVALID AT-OM N-AME 
0xl016 PMERR-INVALID-INTEGER ATOM 
0xl017 PMERR-ATOM N-AME NOT-FOUND 


The WinLoadFilelcon function loads a file icon and returns a 
pointer to it. hptrsuccess contains the icon pointer (NULL 
indicates an error). pszFilename contains the icon filename. 
fprivate contains TRUE if the application wants a private copy 
of the icon. 


The WinLoadHelpTable function provides the module handle 
and help table identity to an instance of the Help Manager. 
fsuccess contains true if this function is successful. 
hwndHelplnstance contains the help manager instance handle. 
idHelpTable contains the identity of the help table. hModule 
contains the handle of the module that contains the help table 
and help subtable resources. 


The WinLoadLibrary function loads a library and makes it 
available to an application. hlibLibhandle contains the library 
handle (NULLHANDLE indicates that the library was not 
loaded). hab contains the anchor block handle. pszLibname 
contains the library name. 
The WinLoadMenu function creates a menu window from a 
menu template. hwndMenu contains the menu window handle. 
hwndowner contains the owner window handle 
(HWND_DESKTOP, HWND_OBJECT, or any other window 
handle). Besource contains the resource identifier 
(NULLHANDLE indicates that the resource is in the application 
EXE file). idMenuid contains the menu identifier within the 
resource. 


Function 


lLenoth = 
WinLoadMessage (hab, 
hmodMod, ulld, 
lcchMax, pszBuffer) 


hptr = WinLoadpointer 
(hwndDesktop, 
Besource, idpointer) 


pwndproc = 
WinLoadprocedure 
(hab, hlibLibhandle, 
pszprocname) 


lLength = 
WinLoadstring (hab, 
Besource, idstring, 
lBufferMax, pszBuffer) 


flocked = 
WinLockvisBegions 
(hwndDesktop, fLock) 


Description 


The WinLoadMessage function loads a message from a 
resource, copies the message to the specified buffer, and adds a 
terminating null character. ILength contains the length of the 
returned string (0 indicates an error). hab contains the anchor 
block handle. hmodMod contains the module handle. ulld 
contains the message identifier. The resource ID is calculated 
from the id parameter value passed to this function as follows: 
resource ID = (id / 16) + 1. IcchMax specifies the size of the 
buffer. pszBuffer is a pointer to the message buffer. 


The WinLoadpointer function loads a pointer from a resource 
file into the system. OS/2 creates a new copy of the pointer 
each time that you call this function. hptr contains the pointer 
handle (NULLHANDLE indicates an error). hwndDesktop 
contains the desktop window handle (HWND_DESKTOP or 
other desktop window handle). Besource contains the identity 
of the pointer definition file (NULLHANDLE indicates the 
application's EXE file). idpointer contains the identify of the 
pointer that you want to load. You can retrieve the last error 
using WinGetLastError. These errors include: 


Oxl001 PMERR INVALID HWND 
0xl00A PMERR-RESOUR-CE NOT FOUND 


The WinLoadprocedure function loads a window or dialog 
procedure from a dynamic link library (DLL). pwndproc 
contains the window procedure identifier (NULL indicates that 
OS/2 could not load the procedure). hab contains the anchor 
block handle. hlibLibhandle contains the library handle. 
pszprocname contains the procedure name. 
The WinLoadstring function loads a string from a resource. It 
automatically adds a terminating null character. ILength 
contains the length of the returned string (0 indicates an error). 
hab contains the anchor block handle. Besource contains the 
resource identifier (NULLHANDLE indicates the application's 
EXE file). idstring contains the string identifier. The resource ID 
is calculated from the id parameter value passed to this function 
as follows: resource ID = (id / 16) + 1. IMaxBuffer specifies the 
size of the buffer. pszBuffer is a pointer to the message buffer. 
You can retrieve the last error using WinGetLastError. These 
errors include: 


Oxl00A PMERR RESOURCE NOT FOUND 


The WinLockvisRegions function locks or unlocks the visible 
regions of all the windows onscreen. This prevents any visible 
region from changing. fLocked contains TRUE if the screen is 
successfully locked. hwndDesktop contains the desktop window 
handle (HWND_DESKTOP or other desktop window handle). 
f Lock contains TRUE if you want to lock the visible regions. 


Table 3 -43 Continued 


Function 


fsuccess = 
WinLockwindowupdate 
(hwndDesktop, 
hwndLockupdate) 


fsuccess = 
WinMakepoints (hab, 
pwptppt, ccount) 


fsuccess = 
WinMakeBect (hab, 
pwrcprc) 


fsuccess = 
WinMapDIgpoints 
(hwndDlg, aptlpoints 
ulcount, foptions) 


fsuccess = 
WinMapwindowpoints 
(hwndFrom, hwndTo, 
aptlpoints, lcount) 


Description 


You can retrieve the last error using WinGetLastError. These 
errors include: 


Oxl001 PMERR INVALID HWND 
The WinLockwindowupdate function disables or enables output 
to a window and its descendants. fsuccess contains true if this 
function is successful. hwndDesktop contains the desktop 
window handle (HWND_DESKTOP or other desktop window 
handle). hwndLockupdate contains the handle of the window 
where you want to prevent output (NULLHANDLE enables 
output in the locked window and its descendants). 
The WinMakepoints function converts points to graphics points 
(from a WPOINT structure to a POINTL structure). fsuccess 
contains true if this function is successful. hab contains the 
anchor block handle. pwptppt contains the points that you want 
to convert. ccount contains the number of points to convert. 
The WinMakeRect function converts a rectangle to a graphics 
rectangle (from a WRECT structure to a RECTL structure). 
fsuccess contains true if this function is successful. hab 
contains the anchor block handle. pwrcprc contains the points 
that you want to convert. 
The WinMapDlgpoints function maps points from dialog 
coordinates to window coordinates. It also can perform the 
reverse function. fsuccess contains true if this function is 
successful. hwndDlg contains the dialog window handle. 
aptlpoints contains the points that you want to map. ulcount 
contains the number of coordinate points. foptions contains the 
calculation control. A value of TRUE maps the dialog 
coordinates into window coordinates relative to the window 
specified by the hwndDlg parameter. You can retrieve the last 
error using WinGetLastError. These errors include: 


Oxl001 PMERR INVALID HWND 


The WinMapwindowpoints function maps a set of points from 
the coordinate space of one window into the coordinate space 
of another window. fsuccess contains true if this function is 
successful. hwndFrom contains the first window handle 
(HWND_DESKTOP maps the points from screen coordinates). 
hwndTo contains the second window handle 
(HWND_DESKTOP maps the points to screen coordinates). 
aptlpoints contains the points that you want to map. ICount 
contains the number of coordinate points (should contain a value 
of 2). You can retrieve the last error using WinGetLastError. 
These errors include: 


Oxl001 PMERR INVALID HWND 


Function 


usBesponse = 
WinMessageBox 
(hwndparent, 
hwndowner, pszText, 
pszTitle, uswindow, 
flstyle) 


Iwindows = 
WinMultwindowFromlDs 
(hwndparent, ahwnd, 
ulFirst, ulLast) 


Description 


The WinMessageBox function creates, displays, and operates a 
message box window. usBesponse contains the user response 
value or an error indicator. hwndDesktop contains the desktop 
window handle (HWND_DESKTOP or other desktop window 
handle). hwndowner contains the owner window handle. 
pszText contains the message box window text. pszTitle 
contains the message box window title (NULL displays the text 
Error as the title of the message box window). uswindow 
contains the message box window identity. flstyle contains the 
message box window style, which includes: MB_OK, 
MB_OKCANCEL, MB_CANCEL, MB_ENTERCANCEL, 
MB_RETRYCANCEL, MB_ABORTRETRYIGNORE , 
MB_YESNO, and MB_YESNOCANCEL. You can specify a 
help button using the MB_HELP style. You also can specify a 
color or icon using the following: MB_NOICON, 
MB_ICONHAND , MB_ICONQUESTION , 
MB_ICONEXCLAMATION , MB_ICONASTERISK, 
MB_INFORMATION, MB_QUERY, MB_WARNING, and 
MB_ERROR. Finally, you can specify a default action using: 
MB_DEFBUITON1, MB_DEFBUTroN2, or 
MB_DEFBUITON3. The modality indicators include: 
MB_APPLMODAL and MB_SYSTEMMODAL. OS/2 allows 
you to determine mobility using MB_MOVEABLE. 
WinMessageBox returns one of the following values: 
0000 MBID ERROR 
0001 MBID-OK 
0002 MBID-CANCEL 
0003 MBID-ABORT 
0004 MBID-RETRY 
0005 MBID-IGNORE 
0006 MBID-YES 
0007 MBID-NO 
You can retrieve the last error using WinGetLastError. These 
errors include: 


Oxl001 PMERR INVALID HWND 
0xl019 PMERR-INVALID-FLAG 
The WinMultwindowFromlDs function finds the handles of the 
child windows that belong to a window. You also can specify a 
range of window identities. (This function is much faster than 
using multiple calls to WinwindowFromlD.) lwindows contains 
the number of window handles returned. hwndparent contains 
the parent window handle. ahwnd contains an array of window 
handles. ulFirst contains the identity of the first window value in 
the range. ulLast contains the identity of the last window value 
in the range. You can retrieve the last error using 
WinGetLastError. These errors include : 


Oxl001 PMERR INVALID HWND 
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Function 


pszNextchar = 
WinNextchar (hab, 
ulcodepage, ulcountry, 
pszcurrentchar) 


fsuccess = 
WinoffsetBect (hab, 
prclBect, lox, ICY) 


fsuccess = 
Winopenclipbrd (hab) 


hdc= 
WinopenwindowDC 
(hwnd) 


fResult = 
WinpeekMsg (hab, 
pqmsgMsg, hwndFilter, 
ulFirst, ulLast, floptions) 


fsuccess = 
WinpopupMenu 
(hwndparent, 


Description 


The WinNextchar function moves to the next character in a 
DBCS string. pszNextchar contains the next character in the 
string (NULL indicates that you reached the end of the string). 
hab contains the anchor block handle. ulcodepage contains 
the codepage. ulcountry contains the country code. 
pszcurrentchar contains the current character in a null 
terminated string. You can retrieve the last error using 
WinGetLastError. These errors include : 


Oxl00B PMERR INVALID_STRING_PARM 


The WinoffsetRect function offsets a rectangle by adding the 
value of lcx to both the left and right coordinates and the value 
of lcY to both the top and bottom coordinates. fsuccess 
contains true if this function is successful. hab contains the 
anchor block handle. prclBect contains the rectangle 
coordinates. lox contains the X offset. ICY contains the Y offset. 


The Winopenclipbrd function opens the clipboard. Opening 
the clipboard allows you to read the objects in it; do not delete 
or modify them. fsuccess contains true if this function is 
successful. hab contains the anchor block handle. 


The WinopenwindowDC function opens a device context for a 
window. (Do not attempt to close this device context using 
DevcloseDC; OS/2 automatically closes it when it closes the 
associated window.) hdc contains a device context handle. 
hwnd contains a window handle. You can retrieve the last error 
using WinGetLastError. These errors include: 


Oxl001 PMERR INVALID HWND 


The WinpeekMsg function inspects the thread's message queue 
and returns to the application with or without a message. 
fBesult returns TRUE if the function returned a message. hab 
contains the anchor block handle. pqmsgMsg contains a 
pointer to the message structure. hwndFilter contains the filter 
window handle. ulFirst contains the first message identify. 
ulLast contains the last message identity. floptions controls 
whether or not OS/2 removes the message (PM_REMOVE or 
PM_NOREMOVE). You can retrieve the last error using 
WinGetLastError. These errors include : 


Oxl001 PMERR INVALID HWND 
0xl019 PMERR-INVALID-FLAG 


The WinpopupMenu function presents a pop-up menu to the 
user. (This is the unanchored equivalent of a pull-down menu.) 
fsuccess contains true if this function is successful. 


Function 


hwndowner, hwndMenu, 
lx, lY, idltem, fsoptions) 


mesult = 
WinpostMsg (hwnd, 
ulMsgld, mpparaml 
mpparam2) 


fsuccess = 
WinpostQueueMsg 
(hmq, ulMsgld, 
mpparaml , mpparam2) 


pszprevchar = 
Winprevchar (hab, 
ulcodepage, ulcountry, 
pszstart, 
pszcurrentchar) 


ulF3esult = 
WinprocessDlg 


Description 


hwndparent contains the parent window handle. hwndowner 
contains the owner window handle. hwndMenu contains the 
menu handle. IX contains the menu position X coordinate. IY 
contains the menu position Y coordinate. idltem contains the 
item identity. Use this parameter if you specified either the 
PU_POSITIONITEM or PU_SELECTITEM parameters in 
fsoptions. fsoptions contains the menu options. There are 
several feature sets you can choose from. The position options 
include PU_POSITIONITEM. The restrain options include: 
PU HCONSTRAIN and PU VCONSTRAIN. The initial state 
options include: PU_MOUSEBUTTON IDOWN, 
PU_MOUSEBUITON2DOWN, 
PU_MOUSEBUTroN3DOWN, and PU_NONE. The select 
options include PU_SELECTITEM. The usage items include: 
PU_KEYBOARD , PU_MOUSEBUTTON 1, 
PU_MOUSEBUITON2, and PU_MOUSEBUTTON3. 


The WinpostMsg function posts a message to the message 
queue associated with the specified window. (This function 
returns immediately while WinpostMsg waits for the receiver to 
return.) fBesult contains TRUE if the message posted 
successfully. hwnd contains the window handle (NULL posts the 
message to the queue associated with the current thread). 
ulMsgld contains the message identity. mpparaml contains 
the first parameter. mpparam2 contains the second parameter. 
You can retrieve the last error using WinGetLastError. These 
errors include: 


Oxl001 PMERR INVALID HWND 


The WinpostQueueMsg function posts a message to a message 
queue. fsuccess contains true if this function is successful. hmq 
contains the message queue handle. ulMsgld contains the 
message identity. mpparam l contains the first parameter. 
mpparam2 contains the second parameter. You can retrieve the 
last error using WinGetLastError. These errors include: 


Oxl002 PMERR_INVALID_HMQ 


The Winprevchar function moves to the previous character in a 
DBCS string. pszprevchar contains the previous character in 
the string. hab contains the anchor block handle. ulcodepage 
contains the codepage. ulcountry contains the country code. 
pszstart contains the character string that contains 
pszcurrentchar. pszcurrentchar contains the current 
character. You can retrieve the last error using WinGetLastError. 
These errors include: 


Oxl00B PMERR INVALID STRING PARM 


The WinprocessDlg function dispatches messages while it 
displays a modal dialog box. If this window has an owner, that 


Table 3-43 
Continued 


Function 


(hwndDlg) 


fsuccess = 
WinptlnBect (hab, 
prclBect, pptlpoint) 


haccelAccel = 
WinQueryAccelTable 
(hab, hwndFrame) 


hwndActive = 
WinQueryActivewindow 
(hwndparent) 


hab= 
WinQueryAnchorBlock 
(hwnd) 


ulRetLen = 
WinQueryAtomLength 
(hatomtblAtomTbl, atom) 


Description 


window is disabled. Of course, this disables all the child windows 
as well. ulBesult contains the reply value (established by the 
WinDismissDlg function). hwndDlg contains the dialog window 
handle. You can retrieve the last error using WinGetLastError. 
These errors include: 


Oxl001 PMERR INVALID HWND 


The WinptlnRect function determines whether a point lies 
within a rectangle. fsuccess contains true if this function is 
successful. hab contains the anchor block handle. prclBect 
contains the rectangle coordinates. pptlpoint contains the point 
coordinates. 


The WinQueryAccelTable function queries the window or queue 
accelerator table. haccelAccel contains the accelerator table 
handle (NULLHANDLE indicates an error). hab contains the 
anchor block handle. hwndFrame contains the frame window 
handle (NULLHANDLE returns the queue accelerator). You can 
retrieve the last error using WinGetLastError. These errors 
include: 


Oxl001 PMERR INVALID HWND 


The WinQueryActivewindow function returns the active window 
for HWND_DESKTOP or other parent window. hwndActive 
contains the active window handle (NULLHANDLE if no 
window is active). hwndparent contains the parent window 
handle (HWND_DESKTOP or other parent window handle). 
You can retrieve the last error using WinGetLastError. These 
errors include : 


Oxl001 PMERR INVALID HWND 


The WinQueryAnchorBlock function returns the anchor block 
handle for the calling window. hab contains the anchor block 
handle. hwnd contains the window handle. You can retrieve the 
last error using WinGetLastError. These errors include: 


Oxl001 PMERR INVALID HWND 


The WinQueryAtomLength function returns the length of the 
specified atom. (This allows the application to determine the 
buffer size required for a WinQueryAtomName call.) ulBetLen 
contains the length of the atom (0 if the atom or atom table is 
invalid). hatomtblAtomTbl contains the atom table handle. atom 
contains the atom whose character-string length you desire. You 
can retrieve the last error using WinGetLastError. These errors 
include: 


Function 


ulF3etLen = 
WinQueryAtomName 
(hatomtblAtomTbl, atom, 
pszBuffer, ulBufferMax) 


ulcount = 
WinQueryAtomusage 
(hatomtblAtomTbl, atom) 


usRetchkst = 
WinQueryButton- 
Checkstate (hwndDlg 
usld) 


hwnd = 
WinQuerycapture 
(hwndDesktop) 


fExists = 
WinQueryclasslnfo (hab, 
pszclassName, 
pclsiclasslnfo) 


Description 


Oxl013 PMERR INVALID HATOMTBL 
0xl014 PMERR-INVALID-ATOM 


The WinQueryAtomName function returns the atom name 
associated with an atom. ulBetLen contains the length of the 
atom (0 if the atom or atom table is invalid). hatomtblAtomTbl 
contains the atom table handle. atom contains the atom you 
want to retrieve. pszBuffer contains a pointer to the buffer used 
to hold the atom character string. ulBufferMax contains length 
of the buffer in bytes. You can retrieve the last error using 
WinGetLastError. These errors include: 


Oxl00B PMERR INVALID STRING FARM 
0xl013 PMERR-INVALID-HATOMFBL 
0xl014 PMERR-INVALID-ATOM 


The WinQueryAtomusage function returns the number of times 
an atom was used. ulcount contains the use count of the atom. 
It returns 65,535 for an integer atom. A return value of 0 
indicates an invalid atom or atom table. hatomtblAtomTbl 
contains the atom table handle. atom contains the atom whose 
use count that you want to retrieve. You can retrieve the last 
error using WinGetLastError. These errors include: 


Oxl013 PMERR INVALID HATOMTBL 
0xl014 PMERR-INVALID-ATOM 


The WinQueryButtoncheckstate function returns the checked 
state of the specified button control. usBetchkst contains the 
checkstate of the specified button control. hwndDlg contains 
the dialog window handle. usld contains the button control 
identity. 


The WinQuerycapture function returns the handle of the 
window that has the pointer captured. hwnd contains the 
handle of the window with the pointer captured 
(NULLHANDLE indicates that either there is no window with 
the pointer captured or an error). hwndDesktop contains the 
desktop window handle (HWND_DESKTOP or other desktop 
window handle). You can retrieve the last error using 
WinGetLastError. These errors include: 


Oxl001 PMERR INVALID HWND 


The WinQueryclasslnfo function returns window class 
information. fExists contains TRUE if the class exists. hab 
contains the anchor block handle. pszclassName contains the 
class name. pclsiclasslnfo contains a pointer to the class 
information structure. You can retrieve the last error using 
WinGetLastError. These errors include: 


Oxl015 PMERR INVALID ATOM NAME 
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Function 


lF3etLen = 
WinQueryclassName 
(hwnd, lLength, 
pchBuffer) 


pthunkpr = 
WinQueryclassThunkproc 
(pszclassName) 


ulData = 
WinQueryclipbrdData 
(hab, ulfmt) 


fExists = 
WinQueryclipbrdFmtlnfo 
(hab, ulfmt, pulFmtlnfo) 


hwndclipbrdowner = 
WinQueryclipbrdowner 
(hab) 


hwndclipbrdviewer = 
WinQueryclipbrdviewer 
(hab) 


ulcodepage = 
WinQuerycp (hmq) 


Description 


Oxl016 PMERR INVALID INTEGER ATOM 
0xl017 PMERR-ATOM N-AME NOT-FOUND 


The WinQueryclassName function copies the window class 
name into a buffer as a null-terminated string. IBetLen contains 
the returned class name length. hwnd contains the window 
handle. ILength contains the length of pchBuffer. pchBuffer 
contains the class name. You can retrieve the last error using 
WinGetLastError. These errors include: 


Oxl001 PMERR INVALID HWND 
0xl00B PMERR-INVALID-STRING PARM 


The WinQueryclassThunkproc function queries the pointer 
conversion procedure associated with a class. pthunkpr 
contains the pointer conversion procedure identifier (NULL 
indicates that no pointer conversion procedure is associated with 
this class). pszclassName contains the window class name. 


The WinQueryclipbrdData function returns a handle to the 
current clipboard data using a specified format. ulData contains 
a handle to the clipboard data (0 indicates that the format does 
not exist or an error occurred). hab contains the anchor block 
handle. ulfmt contains the data format. 


The WinQueryclipbrdFmtlnfo function determines whether the 
clipboard contains a particular data format. If the format exists, 
then the function returns information about it. fExists contains 
true if the ulfmt exists in the clipboard. hab contains the anchor 
block handle. ulfmt contains the format of the data you want to 
query. pulFmtlnfo contains the memory model and usage flags. 
You can retrieve the last error using WinGetLastError. These 
errors include : 


Oxl019 PMERR INVALID FLAG 


The WinQueryclipbrdowner function returns the handle of the 
current clipboard owner. hwndclipbrdowner contains the 
handle of the current clipboard owner (NULLHANDLE indicates 
there is no current clipboard owner or an error occurred). hab 
contains the anchor block handle. 


The WinQueryclipbrdviewer function returns the handle of any 
current viewer Window. hwndclipbrdviewer contains the 
clipboard viewer window handle (NULLHANDLE indicates there 
is no current viewer or an error occurred). hab contains the 
anchor block handle. 


The WinQuerycp function returns the queue codepage for the 
specified message queue. ulcodepage contains the codepage 


Function 


ulTotcount = 
WinQuerycpList (hab, 
ulcount, aulcodepage) 


fcursor = 
WinQuerycursorlnfo 
(hwndDesktop, 
pcsricursorlnfo) 


fsuccess = 
WinQueryDesktopBkgnd 
(hwndDesktop, 
pDeskTopstate) 


hwndDesktop = 
WinQueryDesktopwindow 
(hab, hdc) 


fsuccess = 
WinQueryDlgltemshort 
(hwndDlg, idltem, 


Description 


(0 indicates an error). hmq contains the message queue handle. 
You can retrieve the last error using WinGetLastError. These 
errors include: 


Oxl002 PMERR_INVALID_HMQ 


The WinQuerycpList function returns a list of available 
codepages. ulTotcount contains the total number of available 
codepages (0 indicates an error). hab contains the anchor block 
handle. ulcount contains the number of elements in 
aulcodepage. aulcodepage is an array of codepages. You 
can retrieve the last error using WinGetLastError. These errors 
include: 


Oxl003 PMERR PARAMETER OUT OF RANGE 


The WinQuerycursorlnfo function returns information about 
the current cursor. fcursor contains TRUE if the cursor exists. 
hwndDesktop contains the desktop window handle 
(HWND_DESKTOP or other desktop window handle). 
pcsricursorlnfo contains a pointer to a cursor information 
structure. You can retrieve the last error using WinGetLastError. 
These errors include: 


Oxl001 PMERR INVALID HWND 


The WinQueryDesktopBkgnd returns the desktop structure. 
This contains information about the current state of the desktop 
background. The application making this call must act as the 
OS/2 PM shell in place of the standard IBM shell. fsuccess 
contains true if this function is successful. hwndDesktop 
contains the desktop window handle (HWND_DESKTOP or 
other desktop window handle). pDeskTopstate contains a 
pointer to the desktop state structure. You can retrieve the last 
error using WinGetLastError. These errors include: 


Oxl001 PMERR INVALID HWND 


The WinQueryDesktopwindow function returns the desktop 
window handle. (In most cases, you can use the 
HWND_DESKTOP constant in place of this handle for 
functions that require a desktop window handle.) hwndDesktop 
contains the desktop window handle (NULLHANDLE indicates 
an error). hab contains the anchor block handle. hdc contains 
the device context handle (NULLHANDLE uses the default 
screen device). You can retrieve the last error using 
WinGetLastError. These errors include: 


Ox207C PMERR INVALID HDC 


The WinQueryDlgltemshort function converts the text of a 
dialog item into an integer value. This function is useful for 
converting numeric text input to a binary number. fsuccess 
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Function 


psBesult, fsigned) 


ulBetLen = 
WinQueryDlgltemText 
(hwndDlg, idltem, 
lMaxText, pszText) 


lF3etLen = 
WinQueryDlgTextLength 
(hwndDlg, idltem) 


hwndFocus = 
WinQueryFocus 
(hwndDesktop) 


hwndHelp = 
WinQueryHelplnstance 
(hwndApp) 


sBesNumlt = 
WinQueryLboxcount 
(hwndLbox) 


sRetTxtL = 
WinQueryLboxltemText 


Description 


contains true if this function is successful. hwndDlg contains the 
dialog window handle. idltem contains the identity of the text 
entry to convert. pspesult contains the integer value of the 
conversion. fsigned contains the sign indicator. A value of 
TRUE is signed text that is inspected for a minus sign. You can 
retrieve the last error using WinGetLastError. These errors 
include: 


Oxl001 PMERR INVALID HWND 


The WinQueryDlgltemText function returns a text string from a 
dialog item. You can use this function for any window with 
children. ulBetLen contains the actual number of characters 
returned (0 indicates an error). hwndDlg contains the dialog 
window handle. idltem contains the identity of the item to 
query. IMaxText contains the length of pszText. pszText 
contains the dialog item text string. You can retrieve the last 
error using WinGetLastError. These errors include: 


Oxl001 PMERR INVALID HWND 


The WinQueryDlgTextLength returns the length of the txt string 
in a dialog item. This does not include the null termination 
character. You can use this function for any window with 
children. IBetLen contains the text string length (0 indicates an 
error). hwndDlg contains the dialog window handle. idltem 
contains the identity of the item to query. 


The WinQueryFocus function returns the handle of the focus 
window. hwndFocus contains the handle of the focus window 
(NULL indicates there is no focus window). hwndDesktop 
contains the desktop window handle (HWND_DESKTOP or 
other desktop window handle). You can retrieve the last error 
using WinGetLastError. These errors include: 


Oxl001 PMERR INVALID HWND 


The WinQueryHelplnstance function returns the handle of the 
instance of the Help Manager associated with the specified 
window handle. hwndHelp contains the Help Manager instance 
handle (NULLHANDLE indicates that no Help Manager 
instance is associated with the application window). hwndApp 
contains application window handle. 


The WinQueryLboxcount function returns the number of items 
in the list box. sBesNumlt contains the number of items in the 
list box. hwndLbox contains the list box handle. 


The WinQueryLboxltemText function fills a buffer with the text 
of the indexed item. It also returns the length of the text. 


Function 


(hwndLbox, slndex, 
pszText, scchMax) 


sBetLen = 
WinQueryLboxltem- 
TextLength (hwndLbox, 
slndex) 


sBetlndex = 
WinQueryLbox- 
Selectedltem (hwndLbox) 
fsuccess = 
WinQueryMsgpos 
(hab, pptlptrpos) 


ulTime = 
WinQueryMsgTime (hab) 


hobject = 
WinQueryobject 
(pszobjectld) 


hwndobject = 
WinQueryobjectwindow 
(hwndDesktop) 


hptrpointer = 
WinQuerypointer 
(hwndDesktop) 


fsuccess = 


Description 


sBetTxtL contains the actual length of the copied text. 
hwndLbox contains the list box handle. slndex contains the 
index of the list box item. pszText contains the null terminate 
string. scchMax contains the length of pszText. 


The WinQueryLboxltemTextLength function returns the length 
of the text in the list box item. sBetLen contains the text string 
length. hwndLbox contains the list box handle. slndex contains 
the index of the list box item. 


The WinQueryLboxselectedltem function returns the index of 
the selected list box item. sBetlndex contains the index of the 
selected item. hwndLbox contains the list box handle. 


The WinQueryMsgpos function returns the pointer position 
when the last message obtained from the current message 
queue gets posted in screen coordinates. fsuccess contains 
true if this function is successful. hab contains the anchor block 
handle. pptlptrpos contains the pointer position in screen 
coordinates. 


The WinQueryMsgTime returns the message time for the last 
message retrieve using WinGetMsg or WinpeekMsg from the 
current message queue. This is the time, in milliseconds, since 
the system was started. ulTime contains the time in 
milliseconds. hab contains the anchor block handle. 


The WinQueryobject function returns a handle to the specified 
object. hobject contains the object handle (NULLHANDLE 
indicates the object does not exist or that OS/2 could not 
awaken it). pszobjectld contains the object identification 
(WP_DESKTOP for example). You also can specify a fully 
qualified filename. 
The WinQueryobjectwindow function returns the desktop 
object window handle. hwndobject contains the object window 
handle. hwndDesktop contains the desktop window handle 
(HWND_DESKTOP or other desktop window handle). You can 
retrieve the last error using WinGetLastError. These errors 
include: 


Oxl001 PMERR INVALID HWND 


The WinQuerypointer function returns the pointer handle for 
hwndDesktop. hptrpointer contains the pointer handle 
(NULLHANDLE indicates an error). hwndDesktop contains the 
desktop window handle (HWND_DESKTOP or other desktop 
window handle). You can retrieve the last error using 
WinGetLastError. These errors include: 


Oxl001 PMERR INVALID HWND 


The WinQuerypointerlnfo function returns pointer information. 


_._ I _ - -_ -- 
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Function 


WinQuerypointerlnfo 
(hptr, pptripointerlnfo) 


fsuccess = 
WinQuerypointerpos 
(hwndDesktop, pptlpoint) 


cbBetLen = 
WinQuerypresparam 
(hwnd, idAttrTypel , 
idAttrType2, 
pidAttrTypeFound, 
cbAttrvalueLen, 
pAttrvalue, floptions) 


fsuccess = 
WinQueryQueuelnfo 
(hmq, pmqiMqinfo, 
cbcopied) 


flstatus = 
WinQueryQueuestatus 
(hwndDesktop) 


Description 


fsuccess contains true if this function is successful. hptr 
contains the pointer handle. pptripointerlnfo contains a pointer 
to the pointer information structure. You can retrieve the last 
error using WinGetLastError. These errors include: 


Oxl01B PMERR INVALID HPTR 


The WinQuerypointerpos function returns the pointer position 
of the last message obtained using the WinGetMsg or 
WinpeekMsg functions. fsuccess contains true if this function is 
successful. hwndDesktop contaihs the desktop window handle 
(HWND_DESKTOP or other desktop window handle). pptlpoint 
contains the pointer position in screen coordinates. You can 
retrieve the last error using WinGetLastError. These errors 
include: 


Oxl001 PMERR INVALID HWND 


The WinQuerypresparam function returns the values of the 
presentation parameters for a window. cbBetLen contains the 
length of the parameter value passed back. hwnd contains the 
window handle. idAttrTypel and idAttrType2 contain the first 
and second attribute type identities. pidAttrTypeFound contains 
the attribute type identity found. cbAttrvalueLen contains the 
size of pAttrvalue in bytes. pAttrvalue contains the attribute 
value. floptions contains the options that control the query. 
These controls include: QPF_NOINHERIT, 
QPF_ID ICOLORINDEX, QPF_ID2COLORINDEX, and 
QPF_PURERGBCOLOR. You can retrieve the last error using 
WinGetLastError. These errors include: 


Oxl001 PMERR INVALID HWND 


The WinQueryQueuelnfo function returns information about the 
specified queue. fsuccess contains true if this function is 
successful. hmq contains the message queue handle. 
pmqiMqinfo contains a pointer to the message queue 
information structure. cbcopied contains the size of the 
message queue structure in bytes. 


The WinQueryQueuestatus function returns a code indicating 
the status of the message queue associated with the caller. You 
can use this function to determine if the queue contains 
messages ready for processing. flstatus contains the queue 
status information including the following fields. The summary 
field contains one or more of the following values: QS_KEY, 
QS_MOUSE, QS_MOUSEBUTTON, QS_MOUSEMOVE, 
QS_TIMER, QS_PAINT, QS_SEM1, QS_SEM2, QS_SEM3, 
QS_SEM4, QS_POSTMSG, and QS_SENDMSG. The added 


Function 


ulF}etcode = 
WinQuerysessionTitle 
(hab, ulsession, pszTitle, 
ulTitleLen) 


ulBetcode = 
WinQueryswitchEntry 
(hswitchswitch, 
pswctlswitchData) 


hswitchswitch = 
WinQueryswitchHandle 
(hwnd, idprocess) 


ulcount = 
WinQueryswitchList (hab, 
pswblkBlock, ulLength) 


lF3gbcolor = 
WinQuerysyscolor 
(hwndDesktop, lcolor, 
lBeserved) 


hwndsysModal = 
WinQuerysysModal- 
Window (hwndDesktop) 


Description 


field contains the message type additions. hwndDesktop 
contains the desktop window handle (HWND_DESKTOP or 
other desktop window handle). 


The WinQuerysessionTitle function returns the title under 
which OS/2 started the specified application (or added it to the 
Window List). ulBetcode contains 0 to indicate successful 
completion; any other value signifies an error. hab contains the 
anchor block handle. ulsession contains the OS/2 session 
identity of the application (0 uses the session identity of the 
caller). pszTitle contains the Window List title. ulTitleLen 
contains the length of pszTitle in bytes. If pszTitle is not large 
enough to hold the full title, OS/2 truncates it. 


The WinQueryswitchEntry function returns a copy of the 
Window List data for a specific application. ulBetcode contains 
0 to indicate successful completion; any other value signifies an 
error. hswitchswitch contains the Window List entry handle. 
pswctlswitchData contains a pointer to the switch control data. 
The WinQueryswitchHandle function obtains the Window List 
handle belonging to a window. hswitchswitch contains the 
switch list handle for the specified application (NULLHANDLE 
indicates that the application does not appear in the switch list). 
hwnd contains the window handle (NULLHANDLE indicates 
that application is not an OS/2 application). idprocess 
contains the process identity of the application. 


The WinQueryswitchList function returns information about the 
entries in the Window List. ulcount contains the number of 
switch list entries (0 indicates an error). hab contains the anchor 
block handle. pswblkBlock contains a pointer to the switch 
entries block. Supplying a value of NULL for this parameter 
returns the number of entries in ulcount, but no actual data. 
ulLength contains the length of pswblkBlock in bytes. Use a 0 
for this parameter if you use NULL in pswblkBIock. 


The WinQuerysyscolor function returns the system color. 
IBgbcolor contains the RGB value of the system color. 
hwndDesktop contains the desktop window handle 
(HWND_DESKTOP or other desktop window handle). IColor 
contains the system color index value. You must use one of the 
SYSCLR index values defined under the Winsetsyscolors 
function. Ipeserved is always set to 0. You can retrieve the last 
error using WinGetLastError. These errors include: 


Oxl001 PMERR INVALID HWND 
0xl003 PMERR-PARAME-TER OUT OF RANGE 


The WinQuerysysModalwindow function returns the handle of 
the current system modal window. hwndsysModal contains the 
system modal window handle (NULLHANDLE indicates there is 
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Function 


hptrpointer = 
WinQuerysyspointer 
(hwndDesktop, 
lldentifier, fcopy) 


hatomtblAtomTbl = 
WinQuerysystem- 
AtomTable (VOID) 


lvalue = 
WinQuerysysvalue 
(hwndDesktop, lvalueld) 


Description 


no system modal window). hwndDesktop contains the desktop 
window handle (HWND_DESKTOP or other desktop window 
handle). You can retrieve the last error using WinGetLastError. 
These errors include: 


Oxl001 PMERR INVALID HWND 


The WinQuerysyspointer function returns the system pointer 
handle. hptrpointer contains the pointer handle. hwndDesktop 
contains the desktop window handle. Ildentifier contains the 
system pointer identifier, which includes: SPTR_ARROW, 
SPTR_TEXT, SPTR_WAIT, SPTR_SIZE, SPTR_MOVE, 
SPTR_SIZENWSE , SPTR_SIZENESW, SPTR_SIZEWE, 
SPTR_APPICON , SPTR_ICONINFORMATION , 
SPTR_ICONQUESTION , SPTR_ICONERROR, 
SPTR_ICONWARNING , SPTR_ILLEGAL, SPTR_FILE, 
SPTR_MULTFILE, SPTR_FOLDER, and SPTR_PROGRAM. 
fcopy contains TRUE if you want to create a copy of the 
system pointer and return its handle. Always use this option if 
you plan to modify the system pointer. You can retrieve the last 
error using WinGetLastError. These errors include: 


Oxl001 PMERR INVALID HWND 
0xl003 PMERR-PARAME-TER OUT OF RANGE 


The WinQuerysystemAtomTable function returns the handle of 
the system atom table. hatomtblAtomTbl contains the system 
atom table handle. 


The WinQuerysysvalue function returns the specified system 
value. Ivalue contains the system value (0 indicates an error). 
hwndDesktop contains the desktop window handle 
(HWND_DESKTOP or other desktop window handle). Ivalueid 
contains the system value identifier, which includes: 
SV_CXSCREEN , SV_CYSCREEN, SV_CXVSCROLL, 
SV_CYHSCROLL, SV_CWSCROLLARROW, 
SV_CXHSCROLIARROW, SV_CVIITLEBAR , 
SV_CXBORDER, SV_CYBORDER, SV_CXSIZEBORDER, 
SV_CYSIZEBORDER, SV_CXDLGFRAME , SV_CYDLFRAME , 
SV_CWSLIDER , SV_CXHSLIDER , 
Sv_CXMINMAXBUTroN , SV_CyMINMAXBUITON , 
SV_CYMENU , SV_CXFULLSCREEN , SV_CYFULLSCREEN , 
SV_CXICON, SV_CYICON , SV_CXPOINTER, 
SV_CYPOINTER, SV_DEBUG , SV_CMOUSEBUITONS, 
SV_POINTERLEVEL, SV_CTIMERS , SV_SWAPBUITON , 
SV_CURSORRATE, SV_DBLCLKTIME, SV_CXDBLCLK, 
SV_CYDBLCLK, SV_AIARM , SV_WARNINGFREQ , 
SV_WARNINGDURATION , SV_NOTEFREQ , 


Function 


ulBetcode = 
WinQueryTasksizepos 
(hab, ulld, pswp) 


ulF]etcode = 
WinQueryTaskTitle 
(ulsession, pszTitle, 
ulTitleLen) 


fsuccess = 
WinQueryupdatepect 
(hwnd, prclprc) 


IComplexity = 
WinQueryupdateBegion 


Description 


SV_NOTEDURATION , SV_ERRORFREQ , 
SV_ERRORDURATION , SV_FIRSTSCROLLRATE , 
SV_SCROLLRATE , SV_CURSORLEVEL , 
SV_TRACKRECTLEVEL , SV_CXBYTEALIGN , 
SV_CYBYTEALIGN , SV_SETLIGHTS , SV_INSERTMODE , 
SV_MENUROLLDOWNDEIAY, SV_MENUROLLUPDELAY, 
SV_MOUSEPRESENT, SV_MONOICONS. 
SV_KBDALTERED , SV_PRINTSCREEN , SV_BEGINDRAG , 
SV_ENDDRAG , SV_BEGINSELECT, SV_ENDSELECT, 
SV_OPEN, SV_CONTEXTMENU , SV_TEXTEDIT, 
SV_CONTEXTMENUKB, or SV_TEXTEDITKB. You can 
retrieve the last error using WinGetLastError. These errors 
include: 


Oxl001 PMERR INVALID HWND 
0xl003 PMERR-PARAME-TER OUT OF RANGE 


The WinQueryTasksizepos function returns the recommended 
size, position, and status for the first window of a newly started 
application (typically the main window). These values normally 
come from the initialization file. The system automatically 
generates values if the application does not have an initialization 
file. ulBetcode contains a 0 to indicate successful completion 
(any other value indicates an error). hab contains the anchor 
block handle. ulld contains the session identifier. A value of 0 
uses the caller's session identifier. pswp contains the window 
position and size. It also contains flags showing window 
activation, minimized, or maximized. 


The WinQueryTaskTitle function returns the application's title in 
the Window List. Use the WinQuerysessionTitle function in 
place of this one whenever possible. ulBetcode contains a 
return code of 0 for successful completion (any other value 
indicates an error). ulsession contains the session identity of 
the application. A value of 0 uses the caller's identification. 
pszTitle contains the Window List title. ulTitleLen contains the 
length of pszTitle. 


The WinQueryupdateRect returns the rectangle that bounds the 
update region of a specified window. You can use this function 
to implement an incremental update scheme in place of the 
WinBeginpaint and WinEndpaint functions. fsuccess contains 
true if this function is successful. hwnd contains the window 
handle. prclprc contains the rectangle boundaries in world 
coordinates. You can retrieve the last error using 
WinGetLastError. These errors include : 


Oxl001 PMERR INVALID HWND 


The WinQueryupdateRegion function returns the update region 
of a window. You can use this function to implement an 
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Function 


(hwnd, hrgn) 


flsyslnf = 
WinQueryversion (hab) 


hwndBelated = 
WinQuerywindow 
(hwnd, lcode) 


hdc= 
WinQuerywindowDC 
(hwnd) 


ulModel = 
WinQuerywindow- 
Model (hwnd) 


Description 


incremental update scheme in place of the WinBeginpaint and 
WinEndpaint functions. IComplexity contains the complexity 
and error indicators. hwnd contains the window handle. hrgn 
contains the region handle. WinQueryupdateRegion returns one 
of the following values: 


0000 RGN ERROR 
0001 RGN-NULL 
0002 RGN-RECT 
0003 RGN-COMPLEX 


You can retrieve the last error using WinGetLastError. These 
errors include: 


Oxl001 PMERR INVALID HWND 
0x2034 PMERR-HRGN B-USY 


The WinQueryversion function returns the version, revision 
level, and environment of the PM. flsyslnf contains the system 
information in the following fields: SYSINF_EI\IV (QV_OS2 
equals OS/2), SYSINF_MAJOR (the major version number), and 
SYSINF_MINOR (the minor version and revision level number). 
hab contains the anchor block handle. 


The WinQuerywindow function returns the handle of a window 
that has a specified relationship to the specified window. 
hwndpelated contains the handle of the window related to 
hwnd. hwnd contains the window handle. ICode contains the 
type of information requested. This includes: QW_NEXT, 
QW_PREV, QW_TOP, QW_BOTTOM, QW_OWNER, 
QW_PARENT, QW_NEXITOP, QW_PREVTOP, and 
QW_FRAMEOWNER. You can retrieve the last error using 
WinGetLastError. These errors include: 


Oxl001 PMERR INVALID HWND 
0xl003 PMERR-PARAME-TER OUT OF RANGE 


The WinQuerywindowDC function returns the device context 
for the specified window. hdc contains the device context 
handle (NULLHANDLE indicates no device context or an error 
condition). hwnd contains the window handle. You can retrieve 
the last error using WinGetLastError. These errors include: 


Oxl001 PMERR INVALID HWND 


The WinQuerywindowModel function returns the memory 
associated with the specified window. Use this function to 
determine the memory model used by another application (for 
example, in a DDE transfer). OS/2 version 1.1 and 1.2 
applications do not perform automatic pointer conversion; this 


Function 


fsuccess = 
WinQuerywindowpos 
(hwnd, pswp) 


fsuccess = 
WinQuerywindowprocess 
(hwnd, pidpid, pidTid) 


PP- 
WinQuerywindowptr 
(hwnd, lb) 


fsuccess = 
WinQuerywindowBect 
(hwnd, prclBect) 


lRetLen = 
WinQuerywindowText 


Description 


function makes it possible for a 32-bit application to detect this 
condition and perform the appropriate actions. ulModel 
contains the memory model associated with the window: 
PM_MODEL_1X (16-bit) or PM_MODEL_2X (32-bit). hwnd 
contains the window handle. 


The WinQuerywindowpos function returns the window size and 
position of a visible window. fsuccess contains true if this 
function is successful. hwnd contains the window handle. pswp 
contains a pointer to the SWP structure. You can retrieve the 
last error using WinGetLastError. These errors include: 


Oxl001 PMERR INVALID HWND 
0xl019 PMERR-INVALID-FLAG 


The WinQuerywindowprocess function returns the process and 
thread identity of the thread that created the window. fsuccess 
contains true if this function is successful. hwnd contains the 
window handle. pidpid contains the process identity (PID) of 
the thread that created the window. pidTid contains the thread 
identify (TID) of the thread that created the window. You can 
retrieve the last error using WinGetLastError. These errors 
include: 


Oxl001 PMERR INVALID HWND 


The WinQuerywindowptr function retrieves a pointer value 
from the memory of the reserved window word. pp contains 
the pointer value (NULL indicates an error). hwnd contains the 
window handle. Ib contains a zero-based index of the pointer 
value that you want to retrieve. The valid range is zero through 
(usExtra -4). (usExtra is the WinRegisterclass parameter that 
defines the number of bytes available for application storage.) 
The lb parameter is valid only if all the bytes referenced reside 
within reserved memory. You can retrieve the last error using 
WinGetLastError. These errors include: 


Oxl001 PMERR INVALID HWND 
0xl003 PMERR-PARAME-TER OUT OF RANGE 


The WinQuerywindowRect function returns a window rectangle 
referenced to itself . The bottom-left corner is always at position 
(0, 0). fsuccess contains true if this function is successful. 
hwnd contains the window handle. prclBect contains the 
rectangle boundaries in world coordinates. You can retrieve the 
last error using WinGetLastError. These errors include: 


Oxl001 PMERR INVALID HWND 


The WinQuerywindowText function copies window text into a 
buffer. IBetLen contains the length of the returned text. hwnd 
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Function 


(hwnd, lLength, 
pchBuffer) 


lRetLen = 
WinQuerywindow- 
TextLength (hwnd) 


pthunkpr = 
WinQuerywindowThunk- 
Proc (hwnd) 


ulvalue = 
WinQuerywindowuLong 
(hwnd, lb) 


ulvalue = 
WinQuerywindowushort 
(hwnd, lb) 


Description 


contains the window handle. ILength contains the length of 
pchBuffer. pchBuffer contains the window text. You can 
retrieve the last error using WinGetLastError. These errors 
include: 


Oxl001 PMERR INVALID HWND 


The WinQuerywindowTextLength function returns the length of 
the window text. This does not include the null-termination 
character. IBetLen contains the length of the window text. 
hwnd contains the window handle. You can retrieve the last 
error using WinGetlrdstError. These errors include: 


Oxl001 PMERR INVALID HWND 


The WinQuerywindowThunkproc returns a pointer to the 
pointer-conversion procedure associated with a window. 
pTh unkpr contains the pointer-conversion procedure pointer 
(NULL indicates there is no pointer-conversion procedure 
associated with this window). hwnd contains the window handle. 


The WinQuerywindowuLong function returns the unsigned 
long integer value from a specified offset of the memory of the 
specified reserved window. ulvalue contains the value at the 
specified offset. hwnd contains the window handle. Ib contains 
a zero-based index of the pointer value that you want to retrieve. 
The valid range is zero through (usExtra -4). (usExtra is the 
WinRegisterclass parameter that defines the number of bytes 
available for application storage.) You also can use the following 
QWL values: QWL_HMQ, QWL_STYLE, QWL_HHEAP, 
QWL_FOCUSSAVE, QWL_USER, and QWL_DEFBUITON. 
You can retrieve the last error using WinGetLastError. These 
errors include : 
Oxl001 PMERR INVALID HWND 
0xl003 PMERR-PARAME-TER OUT OF RANGE 
The WinQuerywindowushort function returns the unsigned 
short integer value from a specified offset of the memory of the 
specified reserved window. ulvalue contains the value at the 
specified offset. hwnd contains the window handle. Ib contains 
a zero-based index of the pointer value that you want to retrieve. 
The valid range is zero through (usExtra -4). (usExtra is the 
WinRegisterclass parameter that defines the number of bytes 
available for application storage.) You also can use the following 
QWS values: QWS_ID, QWS_FIAGS, QWS_RESULT, 
QWS_XRESTORE, QWS_YRESTORE , QWS_CXRESTORE, 
QWS_CVAESTORE, QWS_XMINIMIZE, and 
QWS_YMINIMIZE. You can retrieve the last error using 
WinGetLastError. These errors include : 


Function 


lchanged = 
WinBealizepalette 
(hwnd, hps, pcclr) 


fBegistered = 
WinBegisterclass (hab, 
pszclassName, 
pwndproc, flclassstyle, 
usExtra) 


fsuccess = 
WinBegisterobjectclass 
(pszclassName, 
pszModName) 
fsuccess = 
WinBegisteruserDatatype 
(hab, lDatatype, 
lcount, asTypes) 


Description 


Oxl001 PMERR INVALID HWND 
0xl003 PMERR-PARAME-TER OUT OF RANGE 


The WinRealize function initiates the drawing process after 
palette selection. You normally use this function after 
Gpiselectpalette. Ichanged contains the number of remapped 
colors (PAL_ERROR indicates an error). hwnd contains the 
window handle. hps contains the presentation space handle. 
pcclr contains the number of physical palette entries changed. 
You can retrieve the last error using WinGetLastError. These 
errors include : 


Oxl001 PMERR INVALID HWND 
0x2033 PMERR-HDC BU-SY 
0x207C PMERR-INV -HDC 
0x2085 PMERR-INV-IN AREA 
0x2110 PMERR-NO -PA-LETTE SELECTED 


The WinRegisterclass function registers a window class. 
fBegistered contains TRUE if OS/2 successfully registered the 
class. hab contains the anchor block handle. pszclassName 
contains the window class name. pwndproc contains the 
window procedure identifier. Use NULL if the application does 
not provide its own window procedure. flclassstyle contains 
the default window style. usExtra contains the amount of 
reserved storage required for each window created of this class. 
You can retrieve the last error using WinGetLastError. These 
errors include: 


Oxl013 PMERR INVALID HATOMTBL 
0xl015 PMERR-INVALID-ATOM NAME 
0xl016 PMERR-INVALID-INTEGER ATOM 
0xl017 PMERR-ATOM N-AME NOT-FOUND 
Oxioi9 PMERR-INVALID FLAG 


The WinRegisterobjectclass function registers a workplace 
object class. fsuccess contains true if this function is successful. 
pszclassName contains the window class name. pszModName 
contains the name of the DLL that holds the object definition. 
The WinRegisteruserDatatype function registers a data type and 
defines its structure. fsuccess contains true if this function is 
successful. hab contains the anchor block handle. IDatatype 
contains the code of the data type that you want to define. 
ICount contains the number of elements in asTypes. asTypes 
contains the data type codes. This includes system-defined data 
types and their pointer equivalents, application-defined data 
types and their pointer equivalents, and control data types. 
Simple data types include: DTYP_ATOM, DTYPE_BIT16, 
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Function 
Description 


DTYP_BIT32, DTYP_BIT8, DTYP_BOOL, DTYP_COUNT2, 
Drvp_cOuNT2B, DTyp_cOuNT2cH , DTyp_cOuNT4B , 
DTYP_CPID , DTYP_ERRORID , DTYP_IDENTITY, 
DTYP_IDENTITY4, DTYP_INDEX2 , DTYP_IPT, 
DTYP_LENGTH2 , DTYP_LENGTH4, DTYP_LONG , 
DTyp_OFFSET2B, Drvp_plD , DTyp_plx, 
DTYP_PROGCATEGORY, DTYP_PROPERTY2 , 
DTYP_PROPERTY4 , DTYP_RESID , DTYP_SEGOFF, 
DTyp_SHORT, DTyp_TID , DTyp_TIME, Drvp_UCHAR, 
DTYP_ULONG, DTYP_USHORT, DTYP_WIDTH4, and 
DTYP_WNDPROC. Handle data types include: DTYP_HAB, 
DTYP_HACCEL, DTYP_HAPP, DTYP_HATOMTBL, 
DTyp_HBITMAp, DTvp_HDc , Drvp_HENUM , Drvp_HINI, 
DTYP_HLIB, DTYP_HMF, DTYP_HMQ , DTYP_HPOINTER, 
DTvp_HPROGRAM, Drvp_HpS , Drvp_HRGN , 
DTYP_HSEM , DTYP_HSPL, Drvp_HSWITCH , and 
DTYP_HWND. Character, string, and buffer data types include: 
DTyp_BVIE, DTyp_CHAR, Drvp_STRL, Drvp_sTRi 6 , 
DTYP_STR32, DTYP_STR64, and DTYP_STR8. Structure 
data types include : DTYP_ACCEL, DTYP_ACCELTABLE, 
Drvp_ARcpARAMs , DTyp_AREABUNDLE, 
DTYP_BITMAPINFO , DTYP_BITMAPINFOHEADER, 
DTYP_BTNCDATA , DTYP_CATCHBUF, 
DTYP_CHARBUNDLE , DTYP_CIASSINFO , 
DTYP_CREATESTRUCT, DTYP_CURSORINFO , 
DTYP_DEVOPENSTRUC , DTYP_DLGTEMPLATE , 
DTYP_DLGITEM , DTYP_ENTRYFDATA, DTYP_FAITRS , 
DTYP_FFDESCS , DTYP_FIXED , DTYP_FONTMETRICS , 
DTYP_FRAMECDATA , DTYP_GRADIENTL, DTYP_HCINFO , 
DTYP_IMAGEBUNDLE , DTYP_KERNINGPAIRS , 
DTYP_LINEBUNDLE , DTYP_MARGSTRUCT, 
Drvp_MARKERBUNDLE , DTyp_MATRlxLF, 
DTYP_MLECTLDATA , DTYP_OVERFLOW, 
DTYP_OWNERITEM , DTYP_POINTERINFO , DTYP_POINTL, 
DTyp_PROGRAMENTRV, DTyp_PROGrvpE , DTYP_QMSG , 
DTYP_RECTL, DTYP_RGB, DTYP_RGNRECT, 
DTYP_SBCDATA , DTYP_SIZEF, DTYP_SIZEL, 
DTvp_SwBLoCK, DTyp_SwCNTRL, Drvp_SwENTRy, 
Drvp_swp, DTyp_TRACKINFo , DTyp_usERBuiTON , 
DTYP_WNDPARAMS, DTYP_WPOINT, DTYP_WRECT, and 
DTYP_XYWINSIZE. Pointer data types include: DTYP_Prm. 
Minimum application data types include: DTYP_USER. Control 
data types include : DTYP_CTL_ARRAY, 
DTYP_CTL_LENGTH , DTYP_CTL_OFFSET, and 
DTYP CTL PARRAY. 


Function 


fsuccess = 
WinBegisteruserMsg 
(hab, ulMsgld, lTypel 
lDirl , lType2, lDir2, 
lTyper) 


fsuccess = 
WinBeleaseHook (hab, 
hmq, lHook, pAddress, 
hModule) 


fsuccess = 
WinBeleaseps (hps) 


Description 


You can retrieve the last error using WinGetLastError. These 
errors include: 


Oxl03E PMERR ARRAY TOO SMALL 
0xl03F PMERR-DATATYPE EivTRY BAD INDEX 
0xl 040 PMERR-DATATYPE-ENTRY-CTL-BAD 
0xl041 PMERR-DATATYPE-ENTRY-CTL-MISS 
0xl 043 PMERR-DATATYPE-ENTRY-NOT-NUM 
0xl 044 PMERR-DATATYPE-ENTRY-NOT-OFF 
0xl 046 PMERR=DATATYPE=NOT_U-NIQUE 
0xl048 PMERR DATATYPE TOO SMALL 


The WinRegisteruserMsg function registers a user message and 
defines its parameters. fsuccess contains true if this function is 
successful. hab contains the anchor block handle. ulMsgld 
contains the message identifier. You must use a value greater 
than WM_USER. OS/2 allows only one definition per message. 
ITypel contains the data type of message parameter 1. Valid 
data types include: DTYPE_BIT16, DTYPE_BIT32, 
Drvp_BIT8, DTyp_BooL, Drvp_LONG, DTvp_SHORT, 
DTYP_UCHAR, DTYP_ULONG , DTYP_USHORT, DTYP_P* , 
and <-DTYP_USER. IDirl contains the direction of message 
parameter 1. If the message parameter is a pointer, then the 
following direction values apply to the contents of the storage 
location: RUM_IN, RUM_OUT, and RUM_INOUT. IType2 
contains the data type of message parameter 2. See the lTypel 
entry. IDir2 contains the direction of message parameter 2. See 
the IDirl entry. ITyper contains the type of message reply. See 
the lTypel entry. The message reply is always an output 
parameter. You can retrieve the last error using 
WinGetLastError. These errors include: 


Oxl045 PMERR DATATYPE INVALID 
0xl047 PMERR-DATATYPE-TOO LONG 
0xl04F PMERR-MSGID Too SMALL 


The WinReleaseHook function releases an application hook 
from the hook chain. fsuccess contains true if this function is 
successful. hab contains the anchor block handle. hmq contains 
the message queue handle (HMQ_CURRENT or 
NULLHANDLE). IHook contains the type of hook chain. 
pAddress contains the address of the hook routine. hModule 
contains the module handle (NULLHANDLE if the hook 
procedure is in the application's EXE file). You can retrieve the 
last error using WinGetLastError. These errors include: 


Oxl002 PMERR_INVALID_HMQ 
0xl003 PMERR PARAMETER OUT OF RANGE 


The WinReleaseps function releases a cache presentation space 
obtained using the WinGetps or WinGetscreen PS call. This 


Table 3 -43 Continued 


Function 


fsuccess = 
WinBemovepresparam 
(hwnd, idAttrType) 


usBetcode = 
WinBemoveswitchEntry 
(hswitchswitch) 


fsuccess = 
WinBeplaceobjectclass 
(pszoldclassName, 
pszNewclassName, 
fBeplace) 


ulFic = 
WinBequestMutexsem 
(hmtx, ulTimeout) 


fsuccess = 


Description 


function works only with cache presentation spaces. fsuccess 
contains true if this function is successful. hps contains the 
presentation space handle. 
The WinRemovepresparam function removes a presentation 
parameter associated with a specific window. fsuccess 
contains true if this function is successful. hwnd contains the 
window handle. idAttrType contains the attribute type identity; 
the type of presentation attribute that you want to remove. You 
can retrieve the last error using WinGetLastError. These errors 
include: 


Oxl001 PMERR INVALID HWND 


The WinRemoveswitchEntry function removes the specified 
entry from the Window List. usBetcode contains 0 to indicate 
a successful completion (any other value indicates an error). 
hswitchswitch contains the switch list entry handle. You can 
retrieve the last error using WinGetLastError. These errors 
include: 


Oxl202 PMERR INVALID SWITCH HANDLE 
0xl 206 PMERR-INVALID-WINDOW- 


The WinReplaceobjectclass function replaces a registered call 
with another registered class. The new class must be a 
descendant of the old class. fsuccess contains true if this 
function is successful. pszoldclassName contains a pointer to 
the zero-terminated name of the class that you want to replace. 
pszNewclassName contains the name of the new class. 
fBeplace replaces the function of the old class with the new 
class when set to TRUE. A value of FALSE undoes the 
replacement by restoring the old class back to its original 
functionality. 


The WinRequestMutexsem function requests ownership of a 
mutex semaphore or waits for a PM message. This function is 
similar to the DosRequestMutexsem function. ulBc contains one 
of the following return codes: NO_ERROR (0), 
ERROR_INVALID_HANDLE (6) , ERROR_INTERRUPT (95), 
ERROR_TOO_MANY_SEM_REQUESTS ( 10 3) , 
ERROR_SEM_OWNER_DIED ( 105) , or ERROR_TIMEOUT 
(640). hmtx contains the mutex semaphore handle. ulTimeout 
contains the time-out in milliseconds. This is the maximum time 
that the call will wait for a semaphore. You also can use a value 
of 0 to indicate an immediate return or -1 to indicate an 
indefinite wait. 


The WinRestorewindowpos function restores the size and 


Function 


WinBestorewindowpos 
(pszAppName, 
pszKeyName, hwnd) 


fsuccess = 
Winsavewindowpos 
(hsvwp, aswpAswp, 
ccSwp) 


lcomplexity = 
Winscrollwindow 
(hwnd, lDx, lDy, 
prclscroll, prclclip, 


e, floptions) 


mresReply = 
WinsendDlgltemMsg 
(hwndDlg, idltem, 
ulMsgld, mpparaml , 
mpparam2) 


Description 


position of the window to its condition the last time you called 
Winstorewindowpos with the same pszAppName and 
pszKeyName values. This function also restores the 
presentation parameters. fsuccess contains true if this function 
is successful. pszAppName contains the application name. 
pszKeyName contains the key name. hwnd contains the 
window handle. 


The Winsavewindowpos function uses an array of SWP 
structures to save the position of a frame window. fsuccess 
contains true if this function is successful. hsvwp contains the 
frame window repositioning process identifier. aswpAswp 
contains an array of SWP structures. ccSwp contains the 
number of elements in aswpAswp. 


The Winscrollwindow function scrolls the contents of a window 
rectangle. IComplexity contains the complexity and error 
indicators. hwnd contains the window handle. IDx contains the 
amount of horizontal scroll to the right in device units. IDy 
contains the amount of vertical scroll upward in device units. 
prclscroll contains the coordinates of the scroll rectangle. 
prclclip contains the coordinates of the clip rectangle. You can 
use a value of NULL to indicate there is no clip rectangle. 
hrgnupdateBgn contains the update region. Use a value of 
NULLHANDLE to indicate there is no update region. 
prclupdate contains the coordinates of the update rectangle. A 
value of NULL indicates there is no update rectangle. floptions 
contains the scroll options including: SW_SCROLLCHILDREN 
and SW INVALIDATERGN. Winscrollwindow returns one of 
thefollo-wingvalues: 


0000 RGN ERROR 
0001 RGN-NULL 
0002 RGN-RECT 
0003 RGN-COMPLEX 


You can retrieve the last error using WinGetLastError. These 
errors include : 


Oxl001 PMERR INVALID HWND 
0xl019 PMERR-INVALID-FLAG 
0x2034 PMERR-HRGN B-USY 


The WinsendDlgltemMsg function sends a message to the 
specified dialog item in a specific dialog window. This function 
is equivalent to the WinsendMsg function. It does not return 
until the dialog item processes the message. mresBeply 
contains the message return information. hwndDlg contains the 
dialog window handle. idltem contains the child window 
identity. ulMsgld contains the message identity. mpparaml 
and mpparam2 contain the first and second message 
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Function 


mresBeply = 
WinsendMsg (hwnd 
ulMsgld, mpparaml 
mpparam2) 


fsuccess = 
WinsetAccelTable (hab, 
haccelAccel, 
hwndFrame) 


fsuccess = 
WinsetActivewindow 
(hwndDesktop, hwnd) 


fsuccess = 
Winsetcapture 
(hwndDesktop, hwnd) 


Description 


parameters. You can retrieve the last error using 
WinGetLastError. These errors include: 


Oxl001 PMERR INVALID HWND 


The WinsendMsg function sends a message to the specified 
window. It also passes two parameters to the window. The 
function does not return until the window processes the 
message and provides a return message. mresBeply contains 
the message return information. hwnd contains the window 
handle. ulMsgld contains the message identity. mpparaml and 
mpparam2 contain the first and second message parameters. 
You can retrieve the last error using WinGetLastError. These 
errors include : 


Oxl001 PMERR INVALID HWND 
0xl007 PMERR-WINDOW- NOT LOCKED 


The WinsetAccelTable function sets the window accelerator or 
queue accelerator table. fsuccess contains true if this function 
is successful. hab contains the anchor block handle. 
haccelAccel contains the accelerator table handle. A value of 
NULLHANDLE removes any accelerator table in effect for the 
window or queue. hwndFrame contains the frame window 
handle. A value of NULLHANDLE sets the queue accelerator 
table. You can retrieve the last error using WinGetLastError. 
These errors include: 


Oxl001 PMERR INVALID HWND 
0xl01A PMERR-INVALID-HACCEL 


The WinsetActivewindow function makes the frame window 
the active window. fsuccess contains true if this function is 
successful. hwndDesktop contains the desktop window handle 
(HWND_DESKTOP or other desktop window handle). hwnd 
contains the window handle. You can retrieve the last error 
using WinGetLastError. These errors include: 


Oxl001 PMERR INVALID HWND 


The Winsetcapture function captures all pointing device 
messages to hwnd. This sends all pointing device input to the 
window even if the pointing device is not near it at the time. 
fsuccess contains true if this function is successful. 
hwndDesktop contains the desktop window handle 
(HWND_DESKTOP or other desktop window handle). hwnd 
contains the window handle. You can retrieve the last error 
using WinGetLastError. These errors include: 


Oxl001 PMERR INVALID HWND 


Function 


fsuccess = 
WinsetclassMsglnterest 
(hab, pszclassName, 
ulMsgclass, IControl) 


fsuccess = 
WinsetclassThunkproc 
(pszclassName, 
pthunkpr) 


fDataplaced = 
WinsetclipbrdData 
(hab, ulh, ulFmt, 
flFmtlnfo) 


fsuccess = 
Winsetclipbrdowner 
(hab, hwnd) 


Description 


The WinsetclassMsglnterest function sets the message interest 
of a window class. fsuccess contains true if this function is 
successful. hab contains the anchor block handle. 
pszclassName contains the window class name. ulMsgclass 
contains the message class for which you want to set an interest 
level (SHIM_ALL selects all messages). IControl contains the 
level of interest for the message class including: 
SMI_INTEREST, SMI_NOINTEREST, and 
SMI_AUTODISPATCH. You can retrieve the last error using 
WinGetLastError. These errors include: 


Oxl001 PMERR INVALID HWND 
The WinsetclassThunkproc function associates a pointer 
conversion procedure with a window class. fsuccess contains 
true if this function is successful. pszclassName contains the 
window class name. pthunkpr contains the pointer conversion 
procedure identifier (NULL disassociates the procedure from 
this class). 
The WinsetclipbrdData function puts data into the clipboard. It 
also frees any data of the specified format already in the 
clipboard. fDataplaced contains true if this function is 
successful. hab contains the anchor block handle. ulh contains a 
generic handle to the data object that you want to place in the 
clipboard. A value of NULLHANDLE sends a 
WM_RENDERFMT message to the clipboard owner window. 
ulFmt contains the format of the data object in ulh. The valid 
format types include: CF_TEXT, CF_DSPTEXT, CF_BITMAP, 
CF_DSPBITMAP, CF_METAFILE, CF_DSPMETAFILE, and 
CF_PALETTE. flFmtl nfo contains information about the type of 
data referenced by ulh. The memory model field includes: 
CFI_POINTER and CFI_HANDLE. The usage flags include: 
CFI_OWNERFREE and CFI OWNERDISPLAY. You can 
retrieve the last error using WinGetLastError. These errors 
include: 


Oxl016 PMERR INVALID INTEGER ATOM 
0xl019 PMERR-INVALID-FIAG 
The Winsetclipbrdowner function sets the current clipboard 
owner window. The owner window receives the following 
clipboard related messages : WM_DESTROYCLIPBOARD , 
WM_HSCROLLCLIPBOARD , WM_PAINTCLIPBOARD , 
WM_RENDERFMT, WM_RENDERALLFMTS , 
WM_SIZECLIPBOARD , and WM_VSCROLLCLIPBOARD. 
fsuccess contains true if this function is successful. hab 
contains the anchor block handle. hwnd contains the window 
handle. A value of NULLHANDLE releases the clipboard owner 
window without establishing a new one. You can retrieve the 
last error using WinGetLastError. These errors include: 
Oxl001 PMERR INVALID HWND 
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Function 


fsuccess = 
Winsetclipbrdviewer 
(hab, 
hwndNewclipviewer) 


fsuccess = 
Winsetcp 
(hmq, ulcodepage) 


hbm= 
WinsetDesktopBkgnd 
(hwndDesktop, 
pDeskTopstate) 


fsuccess = 
WinsetDlgltemshort 
(hwndDlg, idltem, 
usvalue, fsigned) 


fsuccess = 


Description 


The Winsetclipbrdviewer function sets the current clipboard 
viewer window to the specified window. The viewer window 
receives the WM_DRAWCLIPBOARD message when the 
clipboard contents change. fsuccess contains true if this 
function is successful. hab contains the anchor block handle. 
hwndNewclipviewer contains the handle of the viewer 
window. A value of NULLHANDLE releases the current owner 
without establishing a new one. You can retrieve the last error 
using WinGetLastError. These errors include: 


Oxl001 PMERR INVALID HWND 


The Winsetcp function sets the code page for a queue. 
fsuccess contains true if this function is successful. hmq 
contains the message queue handle. ulcodepage contains the 
code page (either of the two pages specified in CONFIG.SYS). 
You can retrieve the last error using WinGetLastError. These 
errors include : 


Oxl002 PMERR_INVALID_HMQ 
0xl00A PMERR RESOURCE NOT FOUND 


The WinsetDesktopBkgnd function sets the desktop window 
state. This function allows an application to present an image in 
the background of the desktop window. The application must 
act as the OS/2 PM shell because the IBM supplied shell 
prevents this action. hbm contains the desktop background 
bitmap handle (NULLHANDLE indicates an error). 
hwndDesktop contains the desktop window handle. 
pDeskTopstate contains a pointer to the desktop state 
structure. You can retrieve the last error using WinGetLastError. 
These errors include: 


Oxl001 PMERR INVALID HWND 
0xl01B PMERR-INVALID-HPTR 


The WinsetDlgltemshort function converts an integer value into 
the text of a dialog item. This function is valid for any window 
with children. fsuccess contains true if this function is 
successful. hwndDIg contains the dialog window handle. idltem 
contains the child window identity. usvalue contains the integer 
value used to generate the dialog item text. fsigned contains 
TRUE if usvalue contains a signed integer value. You can 
retrieve the last error using WinGetLastError. These errors 
include: 


Oxl001 PMERR INVALID HWND 


The WinsetDlgltemText function sets a text string in a dialog 


Function 


WinsetDlgltemText 
(hwndDlg, idltem, 
pszText) 


fsuccess = 
WinsetFilelcon 
(pszFilename, plcon) 


fsuccess = 
WinsetFocus 
(hwndDesktop, 
hwndNewFocus) 


fsuccess = 
WinsetHook (hab, 
hmq, lHookType, 
pHookproc, hModule) 


fsuccess = 
WinsetKeyboardstate 
Table (hwndDesktop, 
abKeystateTable, fset) 


Description 


item. This function is valid for any window with children. 
fsuccess contains true if this function is successful. hwndDlg 
contains the dialog window handle. idltem contains the child 
window identifier. pszText contains the string that you want to 
set into the dialog item. You can retrieve the last error using 
WinGetLastError. These errors include : 


Oxl001 PMERR INVALID HWND 


The WinsetFilelcon function sets a file's icon. fsuccess 
contains true if this function is successful. pszFilename contains 
the name of the file whose icon that you want to change. plcon 
contains a pointer to an ICONINFO structure. 


The WinsetFocus function sets the focus window. This is 
equivalent to the WinFocuschange function with the 
flFocuschange parameter set to 0. fsuccess contains true if 
this function is successful. hwndDesktop contains the desktop 
window handle (HWND_DESKTOP or other desktop window 
handle). hwndNewFocus contains the handle of the window to 
receive the focus. You can retrieve the last error using 
WinGetLastError. These errors include: 


Oxl001 PMERR INVALID HWND 


The WinsetHook function installs an application procedure into 
a specified hook chain. fsuccess contains true if this function is 
successful. hab contains the anchor block handle. hmq contains 
the message queue handle. Setting hmq to NULLHANDLE 
places the hook in the system hook chain. A value of 
HMQ_CURRENT installs the hook in the message queue 
associated with the current thread. IHookType specifies the 
hook chain type, which includes: HK_CHECKFILTER, 
HK_CODEPAGECHANGE , HK_DESTROYWINDOW, 
HK_HELP, HK_INPUT, HK_JOURNALPLAYBACK, 
HK_JOURNALRECORD , HK_LOADER, 
HK_MSGCONTROL, HK_MSGFILTER, 
HK_REGISTERUSERMSG, and HK_SENDMSG. pHookproc 
contains the address of the application hook procedure. 
hModule contains the handle of the module that contains the 
application hook procedure. Use a value of NULLHANDLE 
when installing the queue hook into an application's own 
message queue. You can retrieve the last error using 
WinGetLastError. These errors include: 


Oxl002 PMERR_INVALID_HMQ 
0xl003 PMERR PARAMETER OUT OF RANGE 


The WinsetKeyboardstateTable function gets or sets the 
keyboard state. This function changes the value returned by the 
WinGetKeystate function but not the WinGetphysKeystate 
function, because it does not affect the physical state of the 
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Function 


fsuccess = 
WinsetLboxltemText 
(hwndLbox, sLboxlndx, 
pszText) 


fsuccess = 
WinsetMenultemText 
(hwndMenu, usld, 
pszText) 


fsuccess = 
WinsetMsglnterest 
(hwnd, ulMsgclass, 
lcontrol) 


fsuccess = 
WinsetMsgMode 
(hab, pszclassName 
lcontrol) 


fsuccess = 
WinsetMultwindowpos 


Description 


keyboard. fsuccess contains true if this function is successful. 
hwndDesktop contains the desktop window handle 
(HWND_DESKTOP or other desktop window handle). 
abKeystateTable is an array that contains a 256-byte table 
indexed by virtual key value. fset sets the keyboard state from 
abKeystateTable when set to TRUE. A value of FALSE copies 
the keyboard state into abKeystateTable. You can retrieve the 
last error using WinGetLastError. These errors include: 


Oxl001 PMERR INVALID HWND 


The WinsetLboxltemText function sets the text of the list box 
indexed item to a buffer. fsuccess contains true if this function 
is successful. hwndLbox contains the list box handle. 
sLboxlndx contains the index of the list box item. pszText 
contains a pointer to a null terminated string. 


The WinsetMenultemText function sets the text for menu 
indexed item to a buffer. fsuccess contains true if this function 
is successful. hwndMenu contains the menu handle. usld 
contains the menu item identifier. pszText contains a pointer to 
a null-terminated string. 


The WinsetMsglnterest function sets a window's message 
interest. fsuccess contains true if this function is successful. 
hwnd contains the window handle. ulMsgclass contains the 
message class. A value of SMIM_ALL sets all messages except 
for WM_QUIT if lcontrol is SMI_AUTODISPATCH or 
SMI NOINTEREST. IControl contains the interest identifier for 
the inessage class. This includes: SMI_RESET, SMI_INTEREST, 
SMI_NOINTEREST, and SMI_AUTODISPATCH. You can 
retrieve the last error using WinGetLastError. These errors 
include: 


Oxl001 PMERR INVALID HWND 


The WinsetMsgMode function sets the mode for generating and 
processing messages for the private window class of an 
application. fsuccess contains true if this function is successful. 
hab contains the anchor block handle. pszclassName contains 
the window class name. IControl contains the message mode 
identifier, which includes: SMD_DELAVED and 
SMD_IMMEDIATE. You can retrieve the last error using 
WinGetLastError. These errors include : 


Oxl001 PMERR INVALID HWND 


The WinsetMultwindowpos function performs the 
Winsetwindowpos function for the specified number of 


Function 


(hab, aswp, cCount) 


fsuccess = 
WinsetobjectData 
(hobject, 
pszsetupstring) 


fsuccess = 
Winsetowner (hwnd, 
hwndNewowner) 


fsuccess = 
Winsetparent (hwnd, 
hwndNewparent, 
fBedraw) 


fsuccess = 
Winsetpointer 
(hwndDesktop, 
hwndNewpointer) 


Description 


windows. It also uses an array of SWP structures; one for each 
window. All the windows must have the same parent. This 
function is more efficient than issuing multiple 
Winsetwindowpos calls. fsuccess contains true if this function 
is successful. hab contains the anchor block handle. aswp 
contains an array of set window position (SWP) structures. 
cCount contains the number of windows you want to position 
(which corresponds to the number of elements in aswp). You 
can retrieve the last error using WinGetLastError. These errors 
include: 


Oxl001 PMERR INVALID HWND 
0xl019 PMERR-INVALID-FLAG 


The WinsetobjectData function sets data on a workplace 
object. fsuccess contains true if this function is successful. 
hobject contains a handle to the workplace object. 
pszsetupstring contains a pointer to a null terminated string 
containing object specific parameters. 


The Winsetowner function changes the owner window of the 
specified window. fsuccess contains true if this function is 
successful. hwnd contains the window handle. 
hwndNewowner contains the handle of the new owner 
window (NULLHANDLE disowns the window). You can retrieve 
the last error using WinGetLastError. These errors include: 


Oxl001 PMERR INVALID HWND 


The Winsetparent function sets the parent for the specified 
window. fsuccess contains true if this function is successful. 
hwnd contains the window handle. hwndNewparent contains 
the handle of the new parent window. A value of 
HWND DESKTOP turns the window into a main window. 
fBedrawi forces a redraw of the window (if required) when set to 
TRUE. You can retrieve the last error using WinGetLastError. 
These errors include: 


Oxl001 PMERR INVALID HWND 
0xl019 PMERR-INVALID-FIAG 


The Winsetpointer function sets the desktop pointer handle. 
fsuccess contains true if this function is successful. 
hwndDesktop contains the desktop window handle 
(HWND_DESKTOP or other desktop window handle). 
hwndNewpointer contains the new pointer handle. A value of 
NULL removes the pointer from the screen. You can retrieve 
the last error using WinGetLastError. These errors include: 


Oxl001 PMERR INVALID HWND 
0xl01B PMERR-INVALID-HPTR 
0x205F PMERR-INV CUR-SOR BITMAP 
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Function 


fsuccess = 
Winsetpointerpos 
(hwndDesktop, lx, lY) 


fsuccess = 
Winsetpresparam 
(hwnd, idAttrType, 
cbAttrvalueLen, 
pAttrvalue) 


fsuccess = 
WinsetBect (hab, 
prclBect, lLeft, lBottom, 
lRight, lTOp) 


fsuccess = 
WinsetBectEmpty 
(hab, prclBect) 


fsuccess = 
WinsetsynchroMode 
(hab, lMode) 


fsuccess = 
Winsetsyscolors 
(hwndDesktop, 
floptions, ulFormat, 
lstart, ulTablen, alTable) 


Description 


The Winsetpointerpos function sets the pointer position. 
fsuccess contains true if this function is successful. 
hwndDesktop contains the desktop window handle 
(HWND_DESKTOP or other desktop window handle). IX 
contains the X position of the pointer in screen coordinates. IY 
contains the Y position of the pointer in screen coordinates. You 
can retrieve the last error using WinGetLastError. These errors 
include: 


Oxl001 PMERR INVALID HWND 


The Winsetpresparam function sets a presentation parameter 
for a window. fsuccess contains true if this function is 
successful. hwnd contains the window handle. idAttrType 
contains one of the system-defined presentation parameter 
attribute types or an application-defined attribute type. 
cbAttrvalueLen contains the length of pAttrvalue in bytes. 
pAttrvalue contains the attribute value. You can retrieve the last 
error using WinGetLastError. These errors include: 


Oxl001 PMERR INVALID HWND 


The WinsetRect function sets rectangle coordinates. fsuccess 
contains true if this function is successful. hab contains the 
anchor block handle. prclBect contains the coordinates of the 
rectangle you want to update. ILeft, IBottom, lBight, and lTop 
contain the new rectangle coordinates. 


The WinsetRectEmpty function sets the coordinates of a 
rectangle to an empty rectangle. It is equivalent to a 
WinsetBect (hab, prclpect, 0, 0, 0, 0) call. fsuccess contains 
true if this function is successful. hab contains the anchor block 
handle. prclBect contains the rectangle coordinates. 


The WinsetsynchroMode function synchronizes the processing 
of messages in an application that uses a distributed message 
queue. fsuccess contains true if this function is successful. hab 
contains the anchor block handle. IMode contains the 
synchronization mode, which includes: SSM_SYNCHRONOUS, 
SSM_ASYNCHRONOUS, and SSM_MIXED. 


The Winsetsyscolors function sets the system color values. It 
sends all main windows in the system a 
WM_SYSCOLORCHANGE message to indicate the change in 
color. After every main window receives this message, the 
system invalidates all windows. This allows the application to 
redraw them with the new colors. fsuccess contains true if this 
function is successful. hwndDesktop contains the desktop 
window handle (HWND_DESKTOP or other desktop window 


Function 


fsuccess = 
WinsetsysModalwindow 
(hwndDesktop, hwnd) 


Description 


handle). floptions contains the color options, which include: 
LCOL RESET and LCOL PURECOLOR. ulFormat contains 
the for-mat of the table entTies. This includes: LCOLF INDRGB 
and LCOLF_CONSECRGB. Istart contains the starting color 
index. The color indexes in order include: 
SYSCLR_ENTRYFIELD , SYSCLR_MENUDISABLEDTEXT, 
SYSCLR_MENUHILITE , SYSCLR_MENUHILITBGND , 
SYSCLR_PAGEBACKGROUND, 
SYSCLR_FIELDBACKGROUND , SYSCLR_BUITONLIGHT, 
SYSCLR_BUITONMIDDLE, SYSCLR_BUITONDARK, 
SYSCLR_BUITONDEFAULT, SYSCLR_SHADOW, 
SYSCLR_ICONTEXT, SYSCLR_DIALOGBACKGROUND , 
SYSCLR_HILITEFOREGROUND, 
SYSCLR HILITEBACKGROUND, 
SYSCLR=INACTIVETITLETEXTBKGD, 
SYSCLR_INACTIVETITLETEXT, 
SYSCLR_ACTIVETITLETEXT, SYSCLR_O UTPUITEXT, 
SYSCLR_WIND OWSTATICTEXT, SYSCLR_S CROLLBAR , 
SYSCLR_BACKGROUND , SYSCLR_ACTIVETITLE , 
SYSCLR_INACTIVETITLE , SYSCLR_MENU , 
SYSCLR_WINDOW, SYSCLR_WINDOWFRAME , 
SYSCLR_MENUTEXT, SYSCLR_WIND OWTEXT, 
SYSCLR_TITLETEXT, SYSCLR_ACTIVEBO RDER , 
SYSCLR_INACTIVEBORDER , SYSCLR_APPWORKSPACE , 
SYSCLR_HELPBACKGROUND , SYSCLR_HELPTEXT, 
SYSCLR_HELPHILITE , SYSCLR_SHADOWHILITEBGND , 
SYSCLR_SHADOWHILITEFGND , and 
SYSCLR SHADOWTEXT. ulTablen contains the number of 
elementsin alTable. alTable contains the start address of the 
application data area containing the color-table definition data. 
Each color value is a 4-byte entry that uses the following 
equation: (Red_Value x 65536) + (Green_Value x 256) + 
Blue_Value. The maximum intensity for each primary color is 
255. You can retrieve the last error using WinGetLastError. 
These errors include: 


Oxl001 PMERR INVALID HWND 
0xl003 PMERR-PARAME-TER OUT OF RANGE 
0xl019 PMERR-INVALID FIA-G 


The WinsetModalwindow function sets the system-modal 
window or ends the system-modal state. When input processing 
enters the system-modal state, all input gets directed to the 
system-modal window or one of its children. Input processing 
resumes its normal state when you destroy the system-modal 
window. fsuccess contains true if this function is successful. 
hwndDesktop contains the desktop window handle or 
HWND DESKTOP. hwnd contains the window handle. A 
handle 5f NULLHANDLE ends the system-modal state and 
returns input processing to its normal state. You can retrieve the 
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Function 


fsuccess = 
Winsetsysvalue 
(hwndDesktop, 
lvalueld, lvalue) 


fsuccess = 
WinsetwindowBits 
(hwnd, Ib, flData, flMask) 


fsuccess = 
Winsetwindowpos 
(hwnd, hwndBehind, lx, 
lY, lox, Icy, floptions) 


Description 


last error using WinGetLastError. These errors include: 


Oxl001 PMERR INVALID HWND 


The Winsetsysvalue function sets a system value. fsuccess 
contains true if this function is successful. hwndDesktop 
contains the desktop window handle or HWND_DESKTOP. 
Ivalueid contains the system value identity, which includes: 
SV_CXSIZEBORDER , SV_CYSIZEBORDER , 
SV_SWAPBUTTON , SV_CURSORRATE, SV_DBLCLKTIME, 
SV_CXDBLCLK, SV_CYDBLCLK, SV_AIARM, 
SV_WARNINGFREQ , SV_WARNINGDURATION , 
SV_NOTEFREQ , SV_NOTEDURATION , SV_ERRORFREQ , 
SV_ERRORDURATION , SV_FIRSTSCROLLRATE , 
SV_SCROLLRATE, SV_SETLIGHTS , SV_INSERTMODE, 
SV_MENUROLLDOWNDELAY, SV_MENUROLLUPDELAY, 
and SV_PRINTSCREEN. Ivalue contains the system value. Use 
milliseconds for time and pels for dimensions. You can retrieve 
the last error using WinGetLastError. These errors include: 


Oxl001 PMERR INVALID HWND 
0xl003 PMERR-PARAME-TER OUT OF RANGE 


The WindowsetwindowBits function sets a number of bits into 
the memory of the reserved window words. fsuccess contains 
true if this function is successful. hwnd contains the window 
handle. Ib contains the zero-based index of the value you want 
to set. You can use any value from zero through (usExtra -4). 
(usExtra is the WinRegisterclass parameter that defines the 
number of bytes available for application storage.) flData 
contains the bit data to store in the window words. flMask 
contains the bits to write indicator. A value of 1 indicates a bit 
that you want to write. 


The Winsetwindowpos function sets the general positioning of 
a window. The window can receive messages from other 
processes or threads during the processing of this function. 
fsuccess contains true if this function is successful. hwnd 
contains the window handle. hwndBehind contains the relative 
window placement order, which includes: HWND_TOP, 
HWND_BOTTOM, or the handle of the sibling window. IX 
contains the X coordinate of the window position. IY contains 
the Y coordinate of the window position. lox contains the 
window width in device units. Icy contains the window height in 
device units. floptions contains the window positioning options. 
These options include: SWP_SIZE, SWP_MOVE, 
SWP_ZORDER, SWP_SHOW, SWP_HIDE, 
SWP_NOREDRAW, SWP_NOADJUST, SWP_ACTIVATE, 


Function 


fsuccess = 
Winsetwindowptr 
(hwnd, lb, pp) 


fF3esult = 
WinsetwindowText 
(hwnd, pszstring) 


fsuccess = 
WinsetwindowThunkproc 
(hwnd, pthunkpr) 


fsuccess = 
WinsetwindowuLong 
(hwnd, lb, ulvalue) 


Description 


SWP_DEACTIVATE, SWP_MINIMIZE, SWP_MAXIMIZE, and 
SWP_RESTORE. You can retrieve the last error using 
WinGetLastError. These errors include: 


Oxl001 PMERR INVALID HWND 
0xl019 PMERR-INVALID-FLAG 


The Winsetwindowptr function sets a pointer value into the 
memory of the reserved window words. fsuccess contains true 
if this function is successful. hwnd contains the window handle. 
Ib contains the zero-based index of the value you want to set. 
You can use any value from zero through (usExtra -4). 
(usExtra is the WinRegisterclass parameter that defines the 
number of bytes available for application storage.) pp contains 
the pointer value that you want to store in the window words. 
You can retrieve the last error using WinGetLastError. These 
errors include: 


Oxl001 PMERR INVALID HWND 
0xl003 PMERR-PARAME-TER OUT OF RANGE 


The WinsetwindowText function sets the window text for the 
specified window. This function sends a 
WM_SETWINDOWPARAMS message to the window identified 
by hwnd. fBesult contains true if this function is successful. 
hwnd contains the window handle. pszstring contains the 
window text. You can retrieve the last error using 
WinGetLastError. These errors include: 


Oxl001 PMERR INVALID HWND 


The WinsetwindowThunkproc function associates a pointer- 
conversion procedure with a window. fsuccess contains true if 
this function is successful. hwnd contains the window handle. 
pthunkpr contains a pointer to the pointer-conversion 
procedure identifier. A value of NULL disassociates any existing 
pointer-conversion procedure from this window. 
The WinsetwindowuLong function sets an unsigned long 
integer value into the memory of the reserved window words. 
hwnd contains the window handle. fsuccess contains true if 
this function is successful. Ib contains a zero-based index of the 
pointer value that you want to set. The valid range is zero 
through (usExtra -4). (usExtra is the WinRegisterclass 
parameter that defines the number of bytes available for 
application storage.) You also can use the following QWL 
values: QWL_HMQ, QWL_STYLE, QWL_HHEAP, 
QWL_FOCUSSAVE, QWL_USER, and QWL DEFBUTTON. 
ulvalue contains the value you want to place al the specified 
offset. You can retrieve the last error using WinGetLastError. 
These errors include: 
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Function 


fsuccess = 
Winsetwindowushort 
(hwnd, lb, usvalue) 


fsuccess = 
Winshowcursor 
(hwnd, fshow) 


fsuccess = 
Winshowpointer 
(hwndDesktop, fshow) 


fsuccess = 
WinshowTrackF3ect 
(hwnd, fshow) 


fsuccess = 
Winshowwindows 
(hwnd, fNewvisibility) 


Description 


Oxl001 PMERR INVALID HWND 
0xl003 PMERR-PARAME-TER OUT OF RANGE 


The Winsetwindowushort function sets an unsigned short 
integer value into the memory of the reserved window words. 
hwnd contains the window handle. fsuccess contains true if 
this function is successful. Ib contains a zero-based index of the 
pointer value that you want to set. The valid range is zero 
through (usExtra -4). (usExtra is the WinRegisterclass 
parameter that defines the number of bytes available for 
application storage.) You also can use the following QWS values: 
QWS_ID , QWS_FIAGS, QWS_RESULT, QWS_XRESTORE, 
QWS_YRESTORE, QWS_CXRESTORE , QWS_CYRESTORE, 
QWS_XMINIMIZE. ulvalue contains the value that you want to 
place at the specified offset. You can retrieve the last error using 
WinGetlrdstError. These errors include: 


Oxl001 PMERR INVALID HWND 
0xl003 PMERR-PARAME-TER OUT OF RANGE 


The Winshowcursor function shows or hides the cursor 
associated with the specified window. fsuccess contains true if 
this function is successful. hwnd contains the window handle. 
fshow contains TRUE if you want to show the cursor. You can 
retrieve the last error using WinGetLastError. These errors 
include: 


Oxl001 PMERR INVALID HWND 


The Winshowpointer function shows or hides a pointer. 
fsuccess contains true if this function is successful. 
hwndDesktop contains the desktop window handle or 
HWND_DESKTOP. fshow contains TRUE if you want to show 
the pointer. You can retrieve the last error using 
WinGetLastError. These errors include : 


Oxl001 PMERR INVALID HWND 


The WinshowTrackRect hides or shows the tracking rectangle. 
fsuccess contains true if this function is successful. hwnd 
contains the window handle. fshow contains TRUE if you want 
to show the tracking rectangle. You can retrieve the last error 
using WinGetLastError. These errors include: 


Oxl001 PMERR INVALID HWND 


The Winshowwindows function sets the visibility state of a 
window. fsuccess contains true if this function is successful. 
hwnd contains the window handle. fNewvisibility contains 
TRUE if you want to make the window visible. You can retrieve 


Function 


fsuccess = 
Winshutdownsystem 
(hab, hmq) 


hApp = WinstartApp 
(hwndNotify, pDetails, 
pszparams, ppeserved 
uloptions) 


ulRet = WinstartTimer 
(hab, hwnd, idTimer, 
ulTimeout) 


fsuccess = 
WinstopTimer (hab, 
hwnd, ulTimer) 


fsuccess = 


Description 


the last error using WinGetLastError. These errors include: 


Oxl001 PMERR INVALID HWND 


The Winshutdownsystem function shuts the system down. 
fsuccess contains true if this function is successful. hab 
contains anchor block handle. hmq contains the message queue 
handle. 


The WinstartApp function starts an application. hApp contains 
the application handle (NULL indicates that OS/2 did not start 
the application). hwndNotify contains the notification window 
handle. Use NULLHANDLE if you do not want OS/2 to post a 
notification message. pDetails contains a pointer to the 
program list structure. pszparams contains any parameters that 
you want to pass to the application. Use a value of NULL if you 
don't want to pass any parameters. pBeserved is a reserved 
parameter, set it to 0. uloptions contains the option indicators, 
which include: 0 (no options selected), 
SAF_INSTALLEDCMDLINE, and SAP_STARTCHILDAPP. You 
can retrieve the last error using WinGetLastError. These errors 
include: 


Oxl200 PMERR DOS ERROR 
0xl206 PMERR-INVA-LID WINDOW 
0xl 208 PMERR-INVALID-PARAMETERS 
0xl530 PMERR-INVALID-APPL 
0xl532 PMERR-STARTE5 IN BACKGROUND 


The WinstartTimer function starts a timer. The window created 
by this function sends out a WM_TIMER message each time the 
timer expires. hab contains the anchor block handle. hwnd 
contains the window handle. When you use a value of 
NULLHANDLE, OS/2 ignores the idTimer parameter and this 
function returns a unique non-zero identity that represents the 
timer. idTimer contains the timer identifier. ulTimeout contains 
the delay time in milliseconds. Using a value of 0 causes the 
timer to time-out as quickly as possible. This is usually an 
interval of 1/8 second. You can retrieve the last error using 
WinGetLastError. These errors include : 


Oxl001 PMERR INVALID HWND 


The WinstopTimer function stops a timer. fsuccess contains 
true if this function is successful. hab contains the anchor block 
handle. hwnd contains the window handle. ulTimer contains 
the timer identifier. You can retrieve the last error using 
WinGetLastError. These errors include : 


Oxl001 PMERR INVALID HWND 


The Winstorewindowpos function saves the current size and 
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Function 


Winstorewindowpos 
(pszAppName, 
pszKeyName, hwnd) 


poldwindowproc = 
Winsubclasswindow 
(hwnd, 
pNewwindowproc) 


IDestRet = 
Winsubstitutestrings 
(hwnd, pszsrc, 
IDestMax, pszDest) 


fNonempty = 
Winsubtractpect (hab, 
prclDest, prclsrcl , 
prclsrc2) 


ulBetcode = 
WinswitchToprogram 
(hswitchswitch) 


Description 


position of the specified window. It also saves the presentation 
parameters. fsuccess contains true if this function is successful. 
pszAppName contains the application name. pszKeyName 
contains the key name. hwnd contains the window handle. 


The Winsubclasswindow function subclasses the specified 
window by replacing its window procedure with another window 
procedure. poldwindowproc contains a pointer to the previous 
window procedure (0 indicates an error). hwnd contains the 
window handle. pNewwindowproc contains a pointer to the 
window procedure used to subclass the window. You can 
retrieve the last error using WinGetLastError. These errors 
include: 


Oxl001 PMERR INVALID HWND 


The Winsubstitutestrings function replaces specific marker 
characters (°/on, where r7 is a number) in a string with text 
supplied by the application. A value of °/o°/o places a "°/o" in the 
destination string without substitution. I DestBet contains the 
actual number of characters returned (0 indicates an error). 
hwnd contains the window handle. pszsrc contains the source 
string. IDestMax contains the size of pszDest. pszDest contains 
the destination string. You can retrieve the last error using 
WinGetLastError. These errors include: 


Oxl001 PMERR INVALID HWND 


The WinsubtractRect function subtracts one rectangle from 
another. Because the subtraction does not always result in a 
rectangular area, this function provides only an approximation 
of the subtraction. When this occurs, it always returns a resultant 
rectangle that is larger than the true subtraction result. While 
this function is much faster than GpicombineRegion, the 
GpicombineRegion function always returns the true result of the 
subtraction. fNonempty contains true if the rectangle is not 
empty. hab contains the anchor block handle. prclDest 
contains the resultant rectangle. prclsrcl and prclsrc2 contain 
the source rectangles. 


The WinswitchToprogram function makes a specific program 
the active program. Only the current foreground application can 
use this call. ulBetcode contains the return code. This includes 
the following values: 0 (successful completion), 
INV_SWITCH_LIST_ENTRY_HANDLE , and 
NOT PERMITTED TO CAUSE SWITCH. hswitchswitch 
contains the Windoiv Li5lt entry handle of the program you want 
to activate. You can retrieve the last error using 


Function 


fTerminated = 
WinTerminate (hab) 


fTerminated = 
WinTerminateApp (happ) 


fsuccess = 
WinTrackBect (hwnd, 
hps, ptiTrackinfo) 


fsuccess = 
WinTranslateAccel (hab, 
hwnd, haccelAccel, 
pQmsg) 


fNonempty = 
Winunionpect (hab, 
prclDesk, prclsrcl , 
prclsrc2) 


fsuccess = 


Description 


WinGetLastError. These errors include: 


Oxl202 PMERR INVALID SWITCH HANDLE 


The WinTerminate function terminates an application thread's 
use of the PM and releases all of its resources. Always destroy 
all windows and message queues and return any cached 
presentation spaces to the cache before issuing this call. 
fTerminated contains TRUE if the application successfully 
terminated. hab contains the anchor block handle. 


The WinTerminateApp function terminates an application 
started using the WinstartApp function using the 
SAF_STARTCHILDAPP option. fTerminated contains TRUE if 
the application successfully terminated. happ contains the 
application handle. You can retrieve the last error using 
WinGetLastError. These errors include: 


Oxl533 PMERR INVALID HAPP 
0xl534 PMERR-CANNof STOP 


The WinTrackRect function draws a tracking rectangle. 
fsuccess contains true if this function is successful. hwnd 
contains the window handle or HWND_DESKTOP. hps 
contains the presentation space handle. A value of 
NULLHANDLE assumes that tracking takes place within hwnd 
and that you did not use the WS_CLIPCHILDREN window 
style. ptiTrackinfo contains the track information. You can 
retrieve the last error using WinGetLastError. These errors 
include: 


Oxl001 PMERR INVALID HWND 


The WinTranslateAccel function translates a WM CHAR 
message in the accelerator table. If haccelAccel-contains 
NULL, then OS/2 assumes that you want to use the current 
table. fsuccess contains true if this function is successful. hab 
contains the anchor block handle. hwnd contains the window 
handle. haccelAccel contains the accelerator table handle. 
pQmsg contains the message that you want to translate. You 
can retrieve the last error using WinGetLastError. These errors 
include: 


Oxl001 PMERR INVALID HWND 
0xl01A PMERR-INVALID-HACCEL 


The WinunionRect function calculates a rectangle that bounds 
the two source rectangles. fNonempty contains true if the 
rectangle is not empty. hab contains the anchor block handle. 
prclDest contains the resultant rectangle. prclsrcl and 
prclsrc2 contain the source rectangles. 
The Winupdatewindow function forces an update of a window 
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Function 


Winupdatewindow 
(hwnd) 


ulBetLen = 
Winupper (hab, 
ulcodepage, ulcountry, 
pszstring) 


uloutchar = 
Winupperchar (hab, 
ulcodepage, ulcountry, 
ullnchar) 


fsuccess = 
WinvalidateBect (hwnd, 
prclBect, 
flncludeclippedchildren) 


fsuccess = 
WinvalidateBegion 
(hwnd, hrgn, 
flncludeclippedchildren) 


Description 


and its associated child windows. fsuccess contains true if this 
function is successful. hwnd contains the window handle. You 
can retrieve the last error using WinGetlrdstError. These errors 
include: 


Oxl001 PMERR INVALID HWND 


The Winupper function converts a string to uppercase. 
ulBetLen contains the length of the converted string. hab 
contains the anchor block handle. ulcodepage contains the 
codepage identifier. Use 0 if you want to use the current process 
code page. ulcountry contains the country code. Use 0 if you 
want to use the default country code in CONFIG.SYS. 
pszstring contains the string that you want to convert. You can 
retrieve the last error using WinGetLastError. These errors 
include: 


Oxl00B PMERR INVALID STRING PARM 


The Winupperchar function translates a character to 
uppercase. uloutchar contains the converted character (0 
indicates an error). hab contains the anchor block handle. 
ulcodepage contains the codepage identifier. Use 0 if you want 
to use the current process code page. ulcountry contains the 
country code. Use 0 if you want to use the default country code 
in CONFIG.SYS. ullnchar contains the character you want to 
convert. You can retrieve the last error using WinGetLastError. 
These errors include: 


Oxl00B PMERR INVALID STRING PARM 


The WinvalidateRect function subtracts a rectangle from the 
update region of an asynchronous paint window. It marks the 
part of the window that is visually valid. Do not use this function 
for CS SYNCPAINT windows. fsuccess contains true if this 
functioL is successful. hwnd contains the window handle. 
prclBect contains the coordinates of the rectangle that you want 
to subtract from the window's update region. 
flncludeclippedchildren contains TRUE if you want to include 
the descendants of hwnd in the valid rectangle. You can retrieve 
the last error using WinGetLastError. These errors include: 


Oxl001 PMERR INVALID HWND 
0xl019 PMERR-INVALID-FLAG 


The WinvalidateRect function subtracts a region from the 
update region of an asynchronous paint window. It marks the 
part of the window that is visually valid. Do not use this function 
for CS SYNCPAINT windows. fsuccess contains true if this 


Function 


ulRc = 
WinwaitEventsem 
(hev, ulTimeout) 


ulRc = 
WinwaitMuxwaitsem 
(hmux, ulTimeout, 
puser) 


fsuccess = 
WinwaitMsg (hab, ulFirst, 
ulLast) 


hwnd - 
WinwindowFromDC (hdc) 


hwnd = 
WinwindowFromlD 
(hwndparent, ulldentifier) 


Description 


function is successful. hwnd contains the window handle. hrgn 
contains the handle of the region that you want to subtract from 
the window's update region. flncludeclippedchildren contains 
TRUE if you want to include the descendants of hwnd in the 
valid rectangle. You can retrieve the last error using 
WinGetLastError. These errors include: 


Oxl001 PMERR INVALID HWND 
0xl019 PMERR-INVALID-FLAG 
0x2034 PMERR-HRGN B-USY 


The WinwaitEventsem function waits for OS/2 to post an 
event semaphore or for a PM message. ulBc contains one of 
the following return codes: NO_ERROR (0), 
ERROR_INVALID_HANDLE (6) , 
ERROR_NOT_ENOUGH_MEMORY (8) , ERROR_INTERRUPT 
(95), or ERROR_TIMEOUT (640). hev contains the event 
semaphore handle. ulTimeout contains the timeout in 
milliseconds. You also can use a value of 0 to indicate an 
immediate return or -1 to indicate an indefinite wait. 


The WinwaitMuxwaitsem function waits for a muxwait 
semaphore to clear or for a PM message. ulBc contains one of 
the following return codes: NO_ERROR (0), 
ERROR_INVALID_HANDLE (6) , 
ERROR_NOT_ENOUGH_MEMORY (8) , 
ERROR_INVALID_PARAMETER (87) , ERROR_INTERRUPT 
(95), or ERROR_TOO_MANY_SEM_REQUESTS (103), 
ERROR_SEM_OWNER_DIED ( 105) , 
ERROR_EMPTY_MUXWAIT (286) , ERROR_MUTEX_DIED 
(287), ERROR_WRONG_TYPE (292), ERROR_TIMEOUT 
(640). hmux contains the muxwait semaphore handle. 
ulTimeout contains the timeout in milliseconds. You also can 
use a value of 0 to indicate an immediate return or -1 to 
indicate an indefinite wait. puser contains a pointer to receive 
the user field from the muxwait semaphore data structure of the 
semaphore that you posted or released. 


The WinwaitMsg function waits for a filtered message. 
fsuccess contains true if this function is successful. hab 
contains the anchor block handle. ulFirst contains the first 
message identity. ulLast contains the last message identity. 


The WinwindowFromDC contains the handle of the window 
corresponding to a particular device context. hwnd contains the 
window handle (NULLHANDLE indicates an error). hdc 
contains the device context handle. 


The WinwindowFromlD function returns the handle of the child 
window with the specified identity. hwnd contains the window 
handle (NULLHANDLE indicates an error). hwndparent 


Table 3 -43 Continued 


Function 


hwndFound = 
WinwindowFrompoint 
(hwndparent, pptlpoint, 
fEnumchildren) 


Description 


contains the parent window handle. ulldentifier contains the 
child window identifier. You can retrieve the last error using 
WinGetLastError. These errors include : 


Oxl001 PMERR INVALID HWND 


The WinwindowFrompoint function finds the window below a 
specified point. This is the descendent of the specified window. 
hwndFound contains the handle of the window beneath 
pptlpoint (NULLHANDLE indicates that pptlpoint is outside 
hwndparent). If this function returns the parent's handle, then 
the point lies outside any of the children associated with 
hwndparent. hwndparent contains the parent window handle 
or HWND_DESKTOP. pptlpoint contains the point that you 
want to test. fEnumchildren contains TRUE if you want to test 
all the descendent windows including child windows of child 
windows. You can retrieve the last error using WinGetLastError. 
These errors include: 


Oxl001 PMERR INVALID HWND 


maREREffiREfflRERE 


NTERACTING with the user is one of the main parts of any 
application in any environment. If you can't receive user input 


and react to it, there is no reason to run the application (unless this is 
a device driver or a background application). This fact doesn't change 
if you program in DOS or OS/2. Of course, there are differences. 
The principles of receiving input between the two environments are 
completely different. An OS/2 application must cope with many 
variables that a DOS application does not even need to recognize. 
How do you know that the current input is meant for your 
application? What do you need to do to interact with both the mouse 
and the keyboard? These are the questions that the OS/2 
programmer must ask. This chapter provides many of the answers 
the programmer needs. It doesn't matter if you want to write a device 
driver, a character-mode application, or an application that works 
with the Workplace Shell (WPS). 


This chapter describes the mouse and keyboard application 
programming interface (API) provided by OS/2. This does include 
user input; it does not include output of this information. Chapter 3 
dealt with fonts and the methods that you use to display them. Think 
of this chapter as the input side of the issues dealt with in chapter 3. 
There are three main sections in this chapter: device driver 
programming, keyboard interface, and mouse interface. 


The device driver section assumes that you want to write a "ring 2" 
device driver application. This section looks at the DOSDevloctl 
functions. You might need to write a special adapter for a unique 
keyboard or your application might need to address the needs of 
input in more than one language. Whatever your needs, this section 
looks at the tools OS/2 provides to help interpret user input. 


The other two sections view programming from the business 
application viewpoint. This includes both the KBD and MOU 
functions. Because OS/2 does not allow direct hardware 
manipulation by ``ring 3" applications, the programmer must use the 
tools supplied by the operating system. This chapter also assumes 
that you want to program for the WPS. (The text will note whether 
the reader can use a particular call for character and graphics mode 
applications.) A unique aspect of this section is that many of the calls 
that you see will work with "Family API" (FAPI) applications as well 
as standard OS/2 applications. This is a special class of application 


that allows you to run under DOS or OS/2. See the VIO functions in 
chapter 3 for a list of functions that allow you to provide output in a 
FAPI as well as input. 


DOSDevloctl functions 


The DOSDevloctl ``functions" all relate to the same OS/2 function call. 
This function provides an expandable IOctl facility that allows you to 
support anything that OS/2 did not build in as part of the operating 
system kernel. It is very generic in nature, much like the DOS software 
interrupt system. In many respects, this is the closest that you ever 
come to programming in the DOS environment under OS/2. This ``one 
call" approach contains the following function elements: 


rc = DOSDevloctl (hDevHandle, ulcategory, ulFunction, ppa]rmList, 
ulparmLengthMax, pparmLengthlnout , pDataArea , ulDataLengthMax, 
pDataLengthlnout ) 


The function provides only one return value. rc contains a return code 
that tells you if the function completed without error. It also contains an 
error code if it didn't. Table 4-1 provides a list of these error codes. 


DOSDevloctl function return codes 
Table 4-1 


Error 
Number Description 


0 NO ERROR 


1 ERROR INVALID FUNCTION 


6 ERROR INVALID HANDLE 


15 ERROR INVALID DRIVE 


31 ERROR GEN FAILURE 


87 ERROR INVALID PARAMETER 


111 ERROR BUFFER OVERFLOW 


115 ERROR PROTECTION VIOLATION 


117 ERROR INVALID CATEGORY 


119 ERROR BAD DRIVER LEVEL 


163 ERROR UNCERTAIN MEDIA 


165 ERROR MONITORS NOT SUPPORTED 


Table 4-2 


As you can see, there are more than a few parameters that you need 
to consider as well. There are three groups of parameters: call 
definition, parameter area parameters, and data area parameters. 
Each parameter group performs a different function as detailed in the 
paragraphs that follow. 


OS/2 Version 1.0 and 1.1 device drivers do not understand generic 
IOctl packets. As a result, the kernel does not pass the 
ulDataLengthMax, pDataLengthlnout, ulparmLengthMax, and 
pparmLengthlnout parameters to the device driver. You must mark 
device drivers level 2 or higher to support receipt of these fields. 


The first group of parameters define the DOSDevloctl function call 
itself . hDevHandle contains a device handle returned by a Dosopen 
call or a standard (open) device handle. ulcategory contains the 
device category in the range from 0 to 255. Table 4-2 provides a list 
of typical device categories. Your computer setup might or might not 
provide other categories. A search of vendor documentation, the INI 
files on your hard drive, and some debugging of the device driver 
itself usually yields the category information for these devices. You 
also can look at the OS/2 2.x Physical Device Reference published by 
IBM. ulFunction contains a device specific function code in the range 
from 0 to 255. As with the category entry, you can find additional 
functions by looking through the vendor documentation, the INI files 
on your system, or the device driver itself . Table 4-3 provides a list of 
common function areas. You OR the required areas together to obtain 
the tens part of a function number. As you can see, all three of these 
parameters require an intimate knowledge of the device driver that 
you want to access and the device that you want to use. 


DOSDevl0Ctl typical categories 


Category 


OxOOO1 


0x0003 


0x0004 


0x0005 


0x0006 


Device 


Serial device 


Video/screen/pointer draw control 


Keyboard 


Printer 


Light-pen (Reserved) 


Category 


Ox0007 


0xOOO8 


0xOOO9 


0xOOOA 


0xOOOB 


Device 


Pointing-device (mouse) 


Disk/diskette 


Physical-disk control 


Character-monitor control 


General device control 


DOSDevloctl typical function areas 


Function 
Area 


Ox0020 


Ox0040 


OxOO80 


Description 


Set this bit to retrieve data or information from the device. If you 
do not use this code (the bit is set to zero), then OS/2 sends 
information or data to the device. 


Set this bit to pass the command to the device driver. If you do not 
set this bit, the operating system kernel intercepts the command. 
IVou must set this bit for most generic I/0 operations.) 


Set this bit if you want the device driver to ignore any commands 
that it does not support. If you do not set this bit, the device driver 
always returns an error code if it does not support the command. 
IVou do not set this bit for most generic I/0 operations.) 


There are three parameter area parameters. Each one defines a 
different part of the input process. pparmList contains the address of 
the command-specific argument list. ulparmLengthMax contains the 
maximum output length of pparmList in bytes. This is not the actual 
length of pparmList for both input and output. pparmLengthlnout 
contains a pointer to the actual length of pparmList. This value can 
exceed ulparmLengthMax on input, but not on output. If this function 
returns ERROR_BUFFER_OVERFLOW, then pparmLengthlnout 
contains the size of the buffer needed to hold the return parameters. 
A NULL value for pparmList tells OS/2 that there is no data area 
defihed for this call. OS/2 automatically ignores the DataLengthMax 
and DataLengthlnout parameters. 


There are three data area parameters. pDataArea contains the data 
area address. ulDataLengthMax contains the maximum output length 
of pDataArea in bytes. This is not the actual length of pDataArea for 
input and output. pDataLengthlnout contains the actual length of 
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Table 4-4 


pDataArea in bytes. The value of this parameter can exceed 
ulDataLengthMax on input, but not output. If this function returns 
ERROR_BUFFER_OVERFLOW, then pDataLengthlnout contains the 
size of the buffer needed to hold the return data. A NULL value for 
pDataArea tells OS/2 that there is no parameter list defined for this 
call. OS/2 automatically ignores the ParmLengthMax and 
ParmListlnout parameters. 


OS/2 provides a number of default device driver functions that you 
can access using this function. Of course, your specific computer 
configuration provides even more opportunities to use it. It always 
pays to search the vendor documentation and the INI files on your 
system. You might want to check the device drivers themselves for 
additional information (provided the software licensing agreement 
does not prevent this action). 


The Borland compiler provides access to these functions through the 
BSEDEV.H and BSEDOS.H include files. The BSEDEV.H file 
contains the entries that you need to actually use the DOSDevloctl 
function. The BSEDOS.H file contains the DOSDevloctl function 
declaration. Both files provide interesting bits of information. You 
might need to check the include files for your compiler to find 
references to these functions because most vendors do not document 
them. In some cases, the vendor uses a new name for the function. 
Fortunately, most vendors include a file with #defines that allow you 
to use the original names. Table 4-4 provides a complete list of the 
keyboard, mouse, and generic DOSDevloctl functions. 


DOSDevloctl generic functions 


Function Name Description 


Video, screen, and pointer drau) control (Category 3) 


Ox0070 Allocate an 


LDT Selector 


This function allocates an LDT selector. The Screen device 
driver grants read/write access to any data area completely withi 
the OxA0000 to OxBFFFF data range. It also grants read-only 
access to the areas between OxOOOOO and OxFFFFF. You cannot 
request access to any areas outside these ranges. The input 
parameter information includes: 32-bit physical address (DWOR] 
and data area length (WORD). The output data information 
includes an LDT selector (WORD). 


Function Name 


Ox0071 


Ox0072 


Ox0073 


Ox0074 


Ox0075 


Ox0076 


Deallocate an 
LDT Selector 


Query Pointer 
Draw Address 


Initialize Call 
Vector Table 


ABIOS 
Pass-Through 


Allocate an 
LDT Selector 
with Offset 


Allocate 
an LDT 
Selector with 
Back Ground 
Validation 
Options 


Description 


This function deallocates an LDT selector that you allocated 
using function Ox0070. The input parameter information 
includes an LDT selector (WORD). There is no data 
information. 


This function returns the pointer draw address. The mouse 
routine uses this address to update the pointer image on 
screen. There is no parameter information. The output data 
information includes: return code (WORD), pointer draw 
routine entry point (DWORD, selector:offset), and pointer 
draw routine data segment (WORD). 


This function initializes the Call Vector Table. There is no 
parameter information. The output data information includes 
the far address of the call vector table (DWORD). 


=±]:sof#{coenoppaesns:3%;ggLOEE#u]:srteEt::5{3eur:i:uoes:fthe 
block to the caller when the function completes. OS/2 
copies the parameter packet to the 64-byte work area used 
as an ABIOS request block. It overwrites the LID and UNIT 
fields with the logical ID of the ABIOS video device opened 
by SCREENS and Unit 0. The input and output parameter 
information includes an ABIOS request block. There is no 
data packet information. 


This function allocates an LDT selector with offset. The 
Screen device driver grants read/write access to any data 
area completely within the OxA0000 to OxBFFFF data 
range. It also grants read-only access to the areas between 
OxOOOOO and OxFFFFF. You cannot request access to any 
areas outside these ranges. The input parameter information 
includes: 32-bit physical address (DWORD) and data area 
length (WORD). The output data information includes: offset 
with new LDT selector OvORD) and LDT selector OvORD). 


This function allocates an LDT selector with background 
validation options. The Screen device driver grants access 
plus a 16-bit option value to customize the allocated memory 
to any data area completely within the OxA0000 to 
OxBFFFF data range. It also grants read-only access to the 
areas between OxOOOOO and OxFFFFF. You cannot request 
access to any areas outside these ranges. The input 
parameter information includes: 32-bit physical address 
(DWORD), data area length (WORD), and an option 
(WORD). The output data information includes an LDT 
selector (WORD). The options include the following values: 
Value Description 


0 Make the segment readable code without background 


validation. 


Table 4-4 Continued 


Function Name Description 


Value Description 


1 Make the segment writable data without background 


validation. 


2 Free the selector. 
3 Make the segment readable IopL code. 
4 Make the segment read/write IopL data. 


Keyboard (Category 4) 


Ox0050 Set code 


Page 


Code Page 
Translation 
Table 


The function changes the device driver resident code page 
for the system and updates the zero entry of the Code Page 
Control Block. The input parameter information includes the 
Code Page Translation Table. There is no data information. 
The Code Page Translation Table contains the following 
elements: 
Offset Ilength Description 


XHeader Ooh 


02h 


04h 


06h 


O8h 


OAh 


Och 


2 usXTableld contains the code page 


number. 


2 fxTableFlagsl contains bits that 


represent the following information: use 
Shift-Alt instead of Ctrl-Alt (0), use the 
left Alt key as Alt-Graphics (1), use the 
right Alt key as Alt-Graphics (2), treat 
the Caps Lock key as the Shift-Lock key 
(3), default table for the language (4), 
toggle the Shift-Lock key when set to 1 
(5), pass on accent keys and beep when 
set to 1 (6), Caps-Shift uses CHAR5 
entry (7), machine dependent table (8), 
reserved (9-15). 


2 fxTableFlags2 is a reserved word; set it 


too. 


2 usKbdType contains the type of 


keyboard installed on the host machine. 


2 usKbdsubType is a reserved word; set it 


too. 


2 usXTableLen contains the length of the 


table. 


2 usEntrycount contains the number of 


KeyDef entries. 


Function Name Description 


Offset Length 
OEh2 


10h2 


12h2 


14h4 


18h 16 


Key Deft 3A:h 2 


3Ch1 


Description 
usEntrywidth contains the width of the 
KeyDef entries. 
usCountry contains the language 
identifier. 
usTableTypelD contains the type 
identifier The first byte contains the type 
identifier. The second byte contains the 
subtype identifier. OS/2 uses a default 
of OxO100. 
ulsubcountrylD contains the sub- 
language identifier. 
Reserved, set these words to 0. 
usxlatop is a record that contains the 
accent flags (AccentFlags) in the first 7 
bits and the key type (KeyType) in the 
next 9 bits. The AccentFlags field 
determines how OS/2 translates a 
standard key into its accented version. 
The KeyType field determines how 
OS/2 treats the key when used with 
various shift keys. There are different key 
types and each type receives different 
treatment. The following list includes the 
various key types: alpha key (01h), non- 
alpha special key (02h), non-alpha 
special key with Caps Lock (03h), non- 
alpha special key with Alt (04h), non- 
alpha special key with Caps Lock and 
Alt, function key (06h), pad key (07h), 
special Ctrl key (08h), Prtsc (09h), 
SysReq (OAh), accent key (also known as 
a dead key) (OBh), Shift key (Och), toggle 
key (like Caps Lock) (ODh), Alt key (OEh), 
Num Lock (OFh), Caps Lock (10h), Scroll 
Lock (llh), extended Shift key (12h), 
extended toggle key (13h), special key 
with Ctrl and Shift (14h), special key with 
Alt and Shift (15h), extended key (1Ah), 
and reserved for the extended key except 
lAh (16h to lFFh). 
The value of charcHARl depends on 
the usKbdType entry. 


]The Code Page Translation Table normally contains 127 KeyDef entries. This table assumes that 


you provided the entire 127 entries. The offset of the AccentTbl entry depends on this 
assumption. 


Table 4-4 Continued 


Function Name 


Ox0051 


Ox0052 


Description 
Offset Length 
3Dh1 


Description 
The value of charcHAR2 depends on 
the usKbdType entry. 


3Eh 1 The value of charcHAR3 depends on 


the usKbdType entry. 


3Fh 1 The value of charcHAR4 depends on 


the usKbdType entry. 


40h 1 The value of charcHAR5 depends on 


the usKbdType entry. 


Accen£Tab`e2 383h 322 Seven 46-byte accent entries 


(AccentEntry). Each field represents one 
flag in the AccentFlag field of the 
usxlatop entry. Each AccentEntry 
element contains the following fields: 
NonAccent (2 bytes), CtIAccent (2 
bytes), AltAccent (2 bytes), Map 1 
through 20 (2 bytes each) 


Set Input 
Mode 


Set Interim 
Character 
Flags 


This function passes the current input mode to the Keyboard 
device driver. This driver maintains a separate entry for each 
session. You can retrieve this information using function 
Ox0071, Ox0074, or Ox0075. The default input mode is 
ASCII. The input parameter information contains Mode 
(BYTE). There are 3 modes as follow: 1xxxxxxlb (1 shift 
report), Oxxxxxxob (ASCII mode), and lxxxxxxxb (BINARY 
mode). There is no data information. This function returns 
the following error codes: 


Ox810C GENERAL FAILURE 
0x8113 INVALID P-ARAMETER 
This function passes the current interim character flags to the 
Keyboard device driver. This driver maintains a separate 
entry for each session. The parameter information includes 
Flag (BYTE). The Flag field contains the following flags: 
reserved (bits 0 through 4), program requested on-the-spot 
conversion (bit 5), reserved (bit 6), and interim console flag 
on toit 7). Set all reserved bits to 0. There is no data 
information. This function returns the following error code: 


Ox8113 INVALID PARAMETER 


0x0053 Set shift state This function sets the current shift state of the keyboard. The 


Keyboard device driver maintains a separate shift state for 
each logical keyboard. The function overrides the shift state 
set by previous shift keystrokes; it does not affect subsequent 


2 There are seven AccentTable entries; one for each accent table bit. 


Function Name 


Ox0054 


Ox0056 


Set Typematic 
Rate And 
Display 


Set Session 
Manager 
Hot Key 


Ox0057 Set KCB 


Ox0058 
Set Code 
Page Number 


Description 
shift keystrokes. The parameter information includes: shift 
state (WORD) and NLS (BYTE). The shift state bits contain 
the following information: right Shift key down (0), left Shift 
key down (1), either Ctrl key down (2), either Alt key down 
(3), Scroll Lock on (4), Num Lock on (5), Caps Lock on (6), 
insert on (7), left Ctrl key down (8), left Alt key down (9), 
right Ctrl key down (10), right Alt key down (11), Scroll Lock 
key down (12), Num Lock key down (13), Caps Lock key 
down (14), and SysReq key down (15). The NLS field 
contains the NLS shift status. There is no data information. 


This function sets the keyboard typematic rate and delay. 
The input parameter information includes: fypematic delay in 
milliseconds (WORD) and typematic rate in characters per 
second (WORD). There is no data information. 


The Session Manager uses this call to set a list of up to 16 
keyboard hot keys. The physical Keyboard device driver 
searches this list and acts on each one the user types. The hot 
keys set by this function affect every OS/2 session. You can 
specify a variety of hot key combinations using shift flags and 
scan codes. This allows for key combinations like Ctrl-Esc. 
The input parameter information includes: state (WORD), 
make scan code (BYTE), break scan code (BYTE), and hot 
key identifier (WORD). The state bits contain the following 
information: right Shift key down (0), left Shift key down (1), 
reserved (2 through 7), left Ctrl key down (8), left Alt key 
down (9), right Ctrl key down (10), right Alt key down (11), 
and reserved (12 through 15). You cannot use the reserved 
value of OxFFFF for the hot key identifier. There is no data 
information. This function returns the following error codes: 


Ox8103 BAD COMMAND 
0x8113 INVA-LID PARAMETER 


This function binds the specified logical keyboard (KCB) to 
the physical keyboard for this session. You must not issue 
this call within the PM session. The input parameter 
information includes the KCB handle (WORD). The default 
handle is 0. There is no data information. This function 
returns the following error codes: 


Ox8103 BAD COMMAND 
0x810C GENERAL FAILURE 


This function sets the code page translation table used by the 
current KCB. You can call this function within a DOS session. 
The input parameter information includes: code page number 
(WORD) and code page layer (WORD). There are two code 
page layers: primary (0) and secondary (1). There is no data 
information. This function returns the following error codes: 


Table 4-4 Continued 


Function Name 


Ox0059 


Ox005A 


Ox005C 


Set Read/ 
Peak 
Notification 


Alter Keyboard 
LEDs 


Set NLS and 
Custom Code 
Page 


Description 


Ox810C GENERAL FAILURE 
0x8113 INVALID P-ARAMETER 


This function sets the read/peak notification. It sets the 
DDFlags of a key packet. This instructs the keyboard device 
driver to send a special monitor packet down the monitor 
chain. The packet appears as part of every Read request seen 
by the physical Keyboard device driver. It continues until you 
terminate the screen group or disable it by calling this 
function again. The Keyboard device driver saves the PID of 
the first caller of this function. Use of this function by another 
PID results in an error. The parameter information includes: 
session number that you want to enable or disable (WORD) 
and read/peak notification flags (WORD). The read/peak flag 
bits include: enable read/peak notification when set to 1 (0) 
and reserved (1 through 15). There is no data information. 
This function returns the following error codes: 


Ox8103 BAD COMMAND 
0x8113 INVA-LID PARAMETER 


This function alters the keyboard LEDs without changing the 
keyboard's mode of scan generation. Only PM can call this 
function. In addition, this function will not change the LED 
status on 88/89 key enhanced keyboards. The parameter 
information includes the state of each LED (WORD). These 
status bits include: Scroll Lock (0), Num Lock (1), Caps Lock 
(2), and reserved (3 through 15). Setting the bit to 1 turns the 
LED on. There is no data information. This function returns 
the following error codes: 


Ox8103 BAD COMMAND 
0x8113 INVA-LID PARAMETER 


This function sets the National Language Support (NLS) and 
custom code page. It installs one of two possible Code Page 
Translation tables into the device driver and updates the 
number 1 or 2 entry of the Code Page Control Block. A 
DOS session can call this function. The parameter 
information includes: Code Page Translation Table pointer 
(DWORD), code page number (WORD), and index to load 
(WORD). There are two standard code page indexes (1 or 2). 
Using a value of -1 indicates that you want to load a custom 
code page (not valid from a DOS session). There is no data 
information. This function returns the following error codes: 


Ox810C GENERAL FAILURE 
0x8113 INVALID P-ARAMETER 


Function Name 


Ox005D 


Ox005E 


Ox0071 


Ox0072 


Ox0073 


Ox0074 


Create a 
New Logical 
Keyboard 


Destroy a 
Logical 
Keyboard 


Query Input 
Mode 


Query Interim 
Character 
Flags 


Query Shift 
State 


Read Character 
Data Records 


Description 


This function creates a new logical keyboard. Use either the 
default code page or one of the two optional code pages 
listed in CONFIG.SYS as the desired initial code page. You 
cannot use this function within a PM application. The input 
parameter information includes: the new logical keyboard 
KCB handle obtained with DosopenHandle (WORD) and the 
initial code page to use with the new logical keyboard 
(WORD). There is no data information. This function returns 
the following error codes: 


Ox8103 BAD COMMAND 
0x810C GENERAL FAILURE 
0x8113 INVALID P-ARAMETER 


This function destroys an existing logical keyboard. You 
cannot call this function from a PM application. The input 
parameter information includes the logical keyboard handle 
(WORD). Use a value of zero for the default keyboard. There 
is no data information. This function returns the following 
error code: 


Ox810C GENERAL FAILURE 


This function returns the input mode of the session of the 
currently active process. There is no parameter information. 
The output data information includes the mode (BYTE). The 
default input mode is ASCII. The input parameter 
information contains Mode (BYTE). There are three modes 
as follow: 1xxxxxxlb (1 shift report), Oxxxxxxob (ASCII 
mode), and lxxxxxxxb (BINARY mode). 


This function returns the interim character flags maintained 
by the physical Keyboard device driver. There is no 
parameter information. The data information includes Flag 
(BYTE). The Flag field contains the following flags: reserved 
(bits 0 through 4), program requested on-the-spot conversion 
(bit 5), reserved (bit 6), and interim console flag on (bit 7). 
This function returns the shift state of the session of the 
currently active process. There is no parameter information. 
The data information includes: shift state (WORD) and NLS 
(BYTE). The shift state bits contain the following information: 
right Shift key down (0), left Shift key down (1), either Ctrl key 
down (2), either Alt key down (3), Scroll Lock on (4), Num 
Lock on (5), Caps Lock on (6), insert on (7), left Ctrl key 
down (8), left Alt key down (9), right Ctrl key down (10), right 
Alt key down (11), Scroll Lock key down (12), Num Lock key 
down (13), Caps Lock key down (14), and SysReq key down 
(15). The NLS field contains the NLS shift status. 
This function returns one or more character data records 
from the keyboard input buffer (KIB) for the session 


Table 4-4 Continued 


Function Name 


Ox0075 
Peek Character 
Data Record 


Description 


of the currently active process. If you set shift report on, then 
the CharData record might contain a shift state change in 
place of a character. You cannot use this function within a 
PM session. The input parameter information includes the 
record transfer count (WORD). If you set this value to 0, then 
the function waits for the number of keystrokes that you 
request. A value of 1 causes the function to return 
immediately. The input/output data information includes the 
CharData record (10 bytes). The CharData fields include: 
ASCII character code (UCHAR), ASCII scan code (the 
numeric value of the character) (UCHAR), state of the 
keystroke event (Status) (UCHAR), reserved (UCHAR), the 
shift key status (WORD), and the time the user pressed the 
key in milliseconds since the system was started (ULONG). 
The Status field contains the shift status in bit 0 (if set to 1 
the shift status returned without a character). Bit 1 contains a 
0 if the scan code is a character. Bits 2 through 4 are 
reserved. Bit 5 requests immediate conversion when set to 1. 
Bits 6 and 7 contain the following information: 00- 
undefined, 01-final character with interim character turned 
off,10-interim character, and 11-final character with 
interim character flag turned on. The shift status bits contain 
the following information: right Shift key down (0), left Shift 
key down (1), either Ctrl key down (2), either Alt key down 
(3), Scroll Lock on (4), Num Lock on (5), Caps Lock on (6), 
insert on (7), left Ctrl key down (8), left Alt key down (9), 
right Ctrl key down (10), right Alt key down (11), Scroll Lock 
key down (12), Num Lock key down (13), Caps Lock key 
down (14), and SysReq key down (15). This function returns 
the following error codes: 


Ox8103 BAD COMMAND 
0x8111 CHA-R CALL INTERRUPTED 
Ox8ii3 INVALID pAinMETER 


This function returns one CharData record from the head of 
the keyboard input buffer (KIB) for the session of the 
currently active process. It does not remove the record from 
the KIB. If you set shift report on, then the CharData record 
might contain a shift state change in place of a character. You 
cannot use this function within a PM session. The parameter 
information includes the KIB status (WORD). Bit 0 contains 1 
if the KIB contained a record. Bit 7 contains 1 if the current 
input mode is binary. The data information contains the 
CharData record (see function Ox0074 for further details). 
This function returns the following error codes: 


Function Name 


Ox0076 


Orxo!OrJfl7 


Ox0078 


Ox0079 


Query Session 
Manager Hot 
Key 


Query 
KeyboardType 


Query Code 
Page Number 


Translate Scan 
Code to ASCII 


Description 


Ox8103 BAD COMMAND 
0x8111 CHA-R CALL INTERRUPTED 
Ox8ii3 INVALID pAinMETER 


This function returns the scan code the physical Keyboard 
device driver uses for the Session Manager hot key. The 
parameter information includes the type of information to 
return (WORD). A value of 0 returns the maximum number 
of hot keys supported by the physical Keyboard device driver. 
A value of 1 returns the hot keys. The data information 
includes: state (WORD), make scan code (BYTE), break scan 
code (BYTE), and hot key identifier (WORD). The state bits 
contain the following information: right Shift key down (0), 
left Shift key down (1), reserved (2 through 7), left Ctrl key 
down (8), left Alt key down (9), right Ctrl key down (10), right 
Alt key down (11), and reserved (12 through 15). This 
function returns the following error code: 


Ox8113 INVALID PARAMETER 


This function returns the keyboard type. The 101-and 
102-key enhanced, 88-and 89-key enhanced, 122-key 
enhanced, and MFl keyboards returns a value of Olh to 
indicate their enhanced status. There is no parameter 
information. The output data information includes: keyboard 
type (WORD) and reserved (DWORD). The keyboard types 
include: 0000h-personal computer AT keyboard, 0001h- 
enhanced keyboard, and 0002h through OOFFh-reserved. 


This function returns the code page in use by the current 
logical keyboard (KCB). You can call this function from a 
DOS session. The parameter information includes: code 
page number (WORD) and reserved (WORD). The code page 
number contains 0 for PC US 437 or -1 for a custom code 
page. Any other value indicates the true code page number. 
There is no data information. 


This function returns an ASCII character translated from a 
scan code. You can specify the code page that you want the 
function to use (default is the current code page). The 
parameter information includes: code page number (WORD) 
and reserved (WORD). The data information includes: 
CharData record (10 bytes, see function Ox0074 for details), 
keyboard device monitor packets (WORD), translation flags 
(WORD), translate state 1 (WORD), and translate state 2 
(WORD). The translation flag bits include: translation complete 
(0) and reserved (1 through 15). Translation state 1 and 2 
contain a 0 When you start the function call and the same 
value when the translation completes. You can reset them to 
zero if you want to stop the current translation and start a new 
one. This function returns the following error code: 


Table 4-4 Continued 


Function Name 


Ox00 7A Query 


Keyboard 
Hardware 
Identification 


Ox007B 
Query 
Keyboard 
Code Page 
Support 
Information 


Description 


Ox8113 INVALID PARAMETER 


This function returns the identifier for the currently attached 
keyboard. There is no parameter information. The input/ 
output data information includes: data length (WORD) and 
hardware identifier (WORD). On input the data length field 
contains the number of data bytes requested by the caller. On 
output, this field contains the maximum length of the data 
available (4 bytes). This function returns the following error 
code: 


Ox8113 INVALID PARAMETER 


The hardware identifiers include: 
Hardware 
ldentifier 


Ooolh 
A841h 
A841h 
A854h 
A854h 
A886h 


Keyboard Type 


PC AT standard keyboard 
101-key enhanced keyboard 
102-key enhanced keyboard 
88-key enhanced keyboard 
89-key enhanced keyboard 
122 key mainframe interactive (MFI) keyboard 


This function returns the keyboard's current code page 
support information. This includes the active code page, 
country, and subcountry. There is no parameter information. 
The data information includes: data length (WORD), code 
page number (WORD), country code in ASCIIZ format 
(ASCIIZ), and subcountry code in ASCIIZ format (ASCIIZ). 
On input, the data length field contains the number of data 
bytes requested by the caller. On output, this field contains 
the maximum length of the data available. This function 
returns the following error code: 


Ox8113 INVALID PARAMETER 


Pointing-device (mouse) (Category 7) 


Ox0051 Notification of 


Display Mode 
Change 


This function notifies the physical Mouse device driver of a 
display mode change. The input parameter information 
includes: length of the data structure in bytes (34 bytes 
maximum) (WORD), mode type (BYTE), number of colors as 
a power of 2 (BYTE), number of text columns (WORD), 
number of text rows (WORD), horizontal resolution (WORD), 
vertical resolution (WORD), attribute format (BYTE), number 
of attributes per character cell (BYTE), 32-bit physical address 
buffer address (DWORD), buffer size required for a full save 
(DWORD), buffer size required for a partial save (DWORD), 


Function Name 


Ox0053 


Ox0054 


Ox0056 


Ox0057 


0x0058 


Reassign 
Current 
Mouse Scaling 
Factors 


Assign New 
Mouse Event 
Mask 


Set Pointer 
Shape 


Unmark 
Collision Area 


Mark Collision 
Area 


Description 


and address of the extended mode data structure (DWORD). 
The mode type bits include: monochrome compatible mode 
(0), text mode when clear or graphics mode when set (1), 
enable color burst when clear (2), VGA compatible modes 
when clear (3), and reserved (4 through 7). The data 
information includes: length of the data structure in bytes 
OvORD), adapter type WORD). display type OvORD), 
display memory in bytes (DWORD), display configuration 
number (WORD), device driver version number (WORD), flag 
bits (WORD), hardware state buffer size (DWORD), full save 
maximum buffer size (DWORD), partial save maximum buffer 
size (DWORD), and offset to mode data (WORD). The 
adapter types include: monochrome (0), CGA (1), EGA (2), 
VGA (3), reserved (4 through 6), and 8514/A (7). The 
display types include: monochrome (0), CGA (1), enhanced 
color (2), 8503 monochrome (3), 8512 or 8512 color (4), 
reserved (5 through 8), and 8514 (9). The flag bits 
include the following values: 0001h-power up display 
configuration, and 0002h-VGA pass through. 


This function reassigns the current mouse scaling factors. 
The default values are: 16 mickeys per 8 pixels for the 
vertical row ratio and 8 mickeys per 8 pixels for the 
horizontal column ratio. The parameter information includes: 
row coordinate scaling factor (WORD) and column 
coordinate scaling factor (WORD). There is no data 
information. 


This function assigns a new mouse event mask. The mask 
determines which event the Mouse driver queues. The 
parameter information includes the event mask (WORD). 
The event mask bits contain: all mouse motion (0), motion 
with button 1 down (1), button 1 is down (2), motion with 
button 2 down (3), button 2 is down (4), motion with button 
3 down (5), button 3 is down (6), and reserved (7 through 
15). There is no data information. 


This function sets the shape of the mouse pointer. The 
current video mode determines the mouse pointer size. The 
parameter information includes: length of the pointer image 
buffer (WORD), pointer image width in columns (WORD), 
pointer image height in rows (WORD), hot spot column 
offset (WORD), and hot spot row offset (WORD). The data 
information is a pointer to the AND pointer image followed 
by the XOR pointer image. 


This function frees the mouse to draw the pointer anywhere 
on the display. There is no parameter or data information. 


This function creates a collision area that restricts the Mouse 
driver from drawing the mouse pointer in that area. The 
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Function Name 


Ox0059 


Ox005A 


Ox005C 


Ox005D 


Ox0060 


Ox0061 


Ox0062 


Specify/ 
Replacepointer 
Screen 
Position 


Set OS/2 
Mode Pointer 
Draw Device 
Driver Address 


Set Current 
Pkysical 
Mouse Device 
Driver Status 
Flags 


Notification of 
Mode Switch 
Completion 


Query Number 
of Mouse 
Buttons 
Supported 


Query Mouse 
Device Motion 
Sensitivfty 


Query Current 
Physical Mouse 
Device Driver 
Status Flag 


Description 


parameter information includes: starting row (WORD), 
starting column (WORD), ending row (WORD), and ending 
column (WORD). There is no data information. 


This function moves the mouse pointer from one area to 
another. It does not draw the pointer if it appears within a 
collision area. The parameter information includes: new row 
position (WORD) and new column position (WORD). There is 
no data information. 


This function specifies the address of the pkysical Pointer 
Draw device driver. This is the routine that receives any 
mouse interrupt requests that affect the pointer image. You 
can use this function only in an OS/2 full-screen session. The 
parameter information includes: pointer draw device driver 
entry point (DWORD) and pointer draw data segment 
selector (DWORD). The second word of the pointer draw 
data segment selector entry is reserved; set it to 0. The data 
information includes: length of the data structure (WORD) 
and caller identification (WORD). Caller identities include: 
application (0) and base video subsystem (BVS) (1). 


This function sets a subset of the current physical Mouse 
device driver status flag. The parameter information includes 
a status flag (WORD). The status flag bits contain the 
following information: reserved (0 through 7), interrupt level 
pointer draw routine not called when set (8), mouse data 
returned in mickeys, not display units, when set (9), and 
reserved (10 through 15). There is no data information. 


This function informs the mouse that a display mode change 
occurred and that it can resume drawing operations. The 
parameter and data information contains a dummy FAR-16 
pointer (DWORD). 
This function returns the number of mouse buttons 
supported by the physical Mouse device driver. There is no 
parameter information. The data information includes the 
number of buttons supported (WORD). 


This function returns the mouse device motion sensitivity. 
There is no parameter information. The data information 
contains the mickeys/centimeter supported by the mouse 
device in the range of 1 to (32K - 1) (WORD). 


This function returns the current physical Mouse device 
driver status flags. There is no parameter information. The 
data information includes the status flags (WORD). The 
status flag bits contain the following information: event queue 


Function Name 


Ox0063 


Ox0064 


Ox0065 


Ox0066 


Ox0067 


Ox0068 


Read Mouse 
Event Queue 


Query Current 
Event Queue 
Status 


Query Current 
Mouse Event 
Mask 


Query Current 
Mouse Scaling 
Factors 


Query Current 
Pointer Screen 
Position 


Description 


busy with I/0 when set (0), block read in progress when set 
(1), flush in progress when set (2), pointer draw routine 
disabled by unsupported mode when set (3), reserved (4 
through 7), interrupt level pointer draw routine not called 
when set (8), mouse data returned in mickeys when set (9), 
and reserved (10 through 15). 


This function reads the FIFO mouse event queue and returns 
its contents. The parameter information includes the type of 
read you want to perform (WORD). There are two read 
types: wait until data is available (0) and return immediately 
(1). The data information includes: mouse event query mask 
(see function Ox0065) (WORD), event time stamp in 
milliseconds (DWORD), pointer row coordinate (WORD), and 
pointer column coordinate (WORD). 
This function returns the number of queued elements in the 
mouse queue. It also returns the maximum number of 
elements allowed in the mouse queue. There is no parameter 
information. The data information includes: the current 
number of queued elements (WORD) and the maximum 
queue size OvORD). 
This function returns the current mouse event mask that can 
include any combination of the event flags set with function 
Ox0054. There is no parameter information. The data 
information includes the event mask (WORD). The event 
mask bits contain: all mouse motion (0), motion with button 
1 down (1), button 1 is down (2), motion with button 2 down 
(3), button 2 is down (4), motion with button 3 down (5), 
button 3 is down (6), and reserved (7 through 15). 


This function returns the current mouse scaling factors. The 
default values are: 16 mickeys per 8 pixels for the vertical 
row ratio and 8 mickeys per 8 pixels for the horizontal 
column ratio. There is no parameter information. The data 
information includes: row coordinate scaling factor (WORD) 
and column coordinate scaling factor (WORD). 


This function returns the current pointer screen position. The 
value that you receive depends on the video mode. Graphic 
modes return pixel values while text modes return character 
position values. There is no parameter information. The data 
information includes: current row position (WORD) and 
current column position (WORD). 


Query pointer This function returns a pointer to the current pointer shape 
Shape 
buffer. The buffer includes both AND XOR masks. The 
parameter information includes: length of the pointer image 
buffer (WORD), pointer image width in columns (WORD), 
pointer image height in rows (WORD), hot spot column 


Table 4-4 Continued 


::_==-I-.---:--_----: 


Function Name 


Ox006A 


Ox006B 


Query Physical 
Mouse Device 
Driver Level 
and Version 


Query Pointing 
Device 
Identification 


Description 


offset (WORD), and hot spot row offset (WORD). The data 
information is a pointer to the AND pointer image followed 
by the XOR pointer image. 


This function returns the physical Mouse device driver level 
and version number. There is no parameter information. The 
data information includes the version number (WORD). 
There are two return values: 1 for OS/21.3 level support 
and 2 for OS/2 2.01evel support. 


This function returns the pointing device identifier. There is 
no parameter information. The data information includes: 
device identification (WORD) and the number of the COM 
port that it's attached to (WORD). OS/2 supports the 
following types of pointers: 


Identifier Pointer ftype 


0 Unknown 


1 Bus mouse 


2 Serial mouse 


3 Import mouse 


4 PS/2 style mouse 


5 IBM 8516 touch display 


6-655 35 Reserved 


Character-monitor control (Category Ah) 


Ox0040 Register a 


Monitor 


This function registers a monitor. Character devices that 
support a monitor receive this request during application calls 
to the DosMonReg function. The parameter information 
includes command information (BYTE). This is a reserved 
field; set it to 0. The data information contains: placement 
flag (refer to the DosMonReg function for more information) 
OvORD), index (refer to the OS/2 Version 2.0 Pkysical 
Device Driver Reference for more information) (WORD), 
address of the monitor input buffer (DWORD), and offset of 
the monitor output buffer (WORD). This function returns the 
following error codes: 


Ox8103 BAD COMMAND 
0x810C GENERAL FAILURE 
0x8112 NO MONITOR SUPPORT 


Function Name Description 


General device control (Category Bh) 


OxOoo 1 Flush Input 


Buffer 


Ox0002 


Ox0041 


Ox0060 


Flush Output 
Buffer 


System 
Notifications 
for Physical 
Device Drivers 


Query Monitor 
Support 


This function flushes an input buffer. The parameter 
information includes command information (BYTE). This is a 
reserved field, set it to 0. The data information includes a 
reserved field, set it to 0 (BYTE). 


This function flushes an output buffer. The parameter 
information includes command information (BYTE). This is a 
reserved field, set it to 0. The data information includes a 
reserved field, set it to 0 (BYTE). 


This function notifies the physical device driver of any 
activities or modifications that occur during session switching. 
This includes any changes to the alternate-input-methods 
interfaces. The parameter information includes: length of the 
data structure in bytes (8, 12, and 24 are the only valid 
values) (BYTE) and notification calling condition (Action) 
made to the physical device driver (WORD). The Action field 
contains the following bit values: pre-session save (0), post- 
session save (1), post-session restore (2), session termination 
(3), session creation (4), start of session switch (5), end of 
session switch (6), AIM pre-save verification (7), AIM post- 
save verification (8), and reserved (9 through 15). The data 
information includes a reserved field, set it to 0 (BYTE). This 
function returns the following error codes: 


Ox810C GENERAL FAILURE 
0x8113 INVALID P-ARAMETER 


This function returns the monitor support status of a 
physical device driver. It returns a value of 
MONITORS NOT SUPPORTED or NO ERROR. The 
parameter information includes command information 
(BYTE). This is a reserved field, set it to 0. The data 
information includes a reserved field, set it to 0 (BYTE). 


Using Table 4-4 is quite simple. The previous paragraphs describe 
the calling syntax for this function. You obtain hDevHandle using an 
open call. The ulcategory entry appears in the heading for each 
group of function calls. The ulFunction entry appears in the first 
column of the table. The rest of the entries (pparmList, 
ulparmLengthMax, pparmLengthlnout, pDataArea, 
ulDataLengthMax, and pDataLengthlnout) appear in the function 
description. Of course, you need to provide the specifics required to 
make this function work. 


KBD functions 


The keyboard (KBD) functions provide an easier and more intuitive 
method of programming the keyboard than resorting to the 
DOSDevloctl function. Of course, you also give up a little flexibility 
to get this ease of use. The functions include the capability not only 
to process keystrokes, but also to perform all the functions required 
in a multitasking environment as well. For example, the KbdGetFocus 
function binds a logical keyboard to the physical keyboard. 


If you could use every KBD function in every programming 
environment, you would seldom need the services of DOSDevloctl. 
Unfortunately, many of these functions have limitations regarding the 
Presentation Manager. There is at least one of the following three 
classifications assigned to each function. You can use FAPI functions 
in a family API application; a family API application runs equally well 
in DOS or OS/2. Presentation Manager will not allow you to use a 
XPM function within an application designed for that environment. 
However, you can use these functions in a windowed OS/2 character- 
mode session. A final restriction is that XWPM functions cannot 
appear in windowed OS/2 character mode sessions; you must restrict 
their use to full-screen sessions only. 


The Borland compiler provides access to these functions through the 
BSESUB.H, BSEERR.H, and BSEDEV.H include files. The 
BSESUB.H file contains the function declarations. The BSEERR.H 
file contains all the error declarations. Finally, the BSEDEV.H file 
contains the constant declarations that you need to actually use the 
KBD functions. You might need to check the include files for your 
compiler to find references to these functions because most vendors 
do not document them. In some cases, the vendor uses a new name 
for the function. Fortunately, most vendors include a file with 
#defines that allow you to use the original names. 


IBM did not choose to document these functions after version 1.3 of 
OS/2 because they are machine specific and IBM plans to port OS/2 
to other platforms. The current OS/2 implementation encourages the 
developer to write to the less machine-specific Presentation Manager 
interface. You still can use all these functions within your current 


applications, but there is no guarantee that IBM will support them in 
future versions of OS/2. Use Presentation Manager specific functions 
whenever possible in your applications. 


Table 4-5 contains a complete listing of the KBD functions. 
Remember, these are the calls supported by OS/2 versions 1.3 and 
above. Versions before 1.3 might or might not support all the listed 
calls. Each entry contains the function classification, calling syntax, 
complete description, and any appropriate errors. It does not include 
any compiler specific calls supported by the Borland (or any other) 
compiler. 


KBD function listing 
Table 4-5 


Function 


FAPI, XPM 
Ushort Kbdcharln 
(pkbci, fwait, hkbd) 


Description 


The Kbdcharln function returns a character data 
(CharData) structure from the keyboard. You must 
make two calls to this function to return DBCS (double-byte 
character codes). If you set the shift report with Kbdsetstatus, then 
this function returns only the changed shift status information. The 
CharData structure does not include the time stamp when you use 
this function within a FAPI application. pkcbi contains a pointer to 
the character data structure. fwait contains 1 if you want to return 
immediately or 0 if you want to wait for a keystroke. hkbd contains 
the keyboard handle. The CharData structure consists of the 
following elements: 
Offset Length Description 


Ooh 1 Keyboard scan code translated into an ASCII 


character code. 


01h1 
02h1 


03h1 


Code received from the keyboard. 


State of the keyboard event. This entry 
contains the following bits: shift status returned 
without character (0), scan code is a character 
when clear or scan code is an extended key 
code when set (1), reserved (2 through 4), 
immediate conversion requested (5), and 
character type (6 and 7). There are four 
character types: undefined (00), final character 
with interim flag off (01), interim character (10) 
and final character with interim flag on (11). 


NLS shift status. This is a reserved field; set it 
too. 


Table 4-5 
Continued 


Function 


XPM 
Ushort Kbdclose 
(hkdb) 


XWPM 
Ushort 
KbdDeBegister 
(VOID) 


FAPI, XPM 
Ushort 
KbdFlushBuffer 
(hkbd) 


Description 
Offset Length Description 


04h 2 The shift key status bits contain the following 


information: right Shift key down (0), left Shift 
key down (1), either Ctrl key down (2), either 
Alt key down (3), Scroll Lock on (4), Num Lock 
on (5), Caps Lock on (6), insert on (7), left Ctrl 
key down (8), left Alt key down (9), right Ctrl 
key down (10), right Alt key down (11), Scroll 
Lock key down (12), Num Lock key down (13), 
Caps Lock key down (14), and SysReq key 
down (15). 


06h4 
Time of key press in milliseconds since the user 
started the system. 


Kbdcharln returns one of the following values: 


0 NO ERROR 


375 ERROR KBD INVALID IOWAIT 
4 3 9 ERROR-KBD-INVALID-HANDLE 
445 ERROR=KBD=FO CUS_REQ UIRED 
447 ERROR KBD KEYBOARD BUSY 
46 4 ERROR-KBD-DETACH ED 
504 ERROR-KBD-EXTENDED SG 


The Kbdclose function closes a logical keyboard. You normally use 
this function when the keyboard has the focus. Using it at other 
times could block other applications. hkbd contains the keyboard 
handle. Kbdclose returns one of the following values: 


0 NO ERROR 


439 ERffoR KBD INVALID HANDLE 
4 6 4 ERRO R-KBD-DETACH-ED 
504 ERROR-KBD-EXTENDED SG 


The KbdDeRegister function deregisters a session's keyboard 
subsystem. KbdDeRegister returns one of the following values: 


0 NO ERROR 


411 ERROR KBD DEREGISTER 
46 4 ERRO R-KBD-DETACHED 
504 ERROR-KBD-EXTENDED SG 


The KbdFlushBuffer function clears the keystroke buffer. hkbd 
contains the keyboard handle. You do not require a handle when 
using this function in a FAPI application. KbdFlushBuffer returns 
one of the following values: 


0 NO ERROR 


439 EREOR KBD INVALID HANDLE 


Function 


XPM 
Ushort 
KbdFreeFocus (hkbd) 


XPM 
Ushort KbdGetcp 
(ulBeserved, 
pidcp, hkbd) 


XPM 
Ushort KbdGetFocus 
(fwait, hkbd) 


XPM 
Ushort KbdGetHWID 
(pkbdHwlD, hkbd) 


Description 


445 ERROR_KBD FOCUS_REQUIRED 
447 ERROR KBD-KEYBOARD BUSY 
46 4 ERROR-RED-DETACHED 
504 ERROR-KBD-EXTENDED SG 


The KbdFreeFocus function severs the bond created by 
KbdGetFocus between a logical and physical keyboard. 
KbdFreeFocus returns one of the following values: 


0 NO ERROR 


439 ERffoR KBD INVALID HANDLE 
445 ERROR=KBD=FO C US_REQ UIRED 
464 ERROR KBD DETACHED 
504 ERROR-KBD-EXTENDED SG 


The KbdGetcp function returns the code page used to translate 
scan codes to ASCII characters. ulBeserved is a reserved 
parameter, set it to 0. pidcp contains the code page identifier. 
hkbd contains the keyboard handle. KbdGetcp returns one of the 
following values: 


0 NO ERROR 


373 EREOR KBD PARAMETER 
439 ERROR-KBD-INVALID HANDLE 
44 5 ERRO R-KBD=FO CUS_REQ UIRED 
447 ERROR-KBD KEYBOARD BUSY 
464 ERRO R-KBD-DETACHED 
504 ERROR-KBD-EXTENDED SG 


The KbdGetFocus function binds the logical keyboard to the 
physical keyboard. fwait contains 0 if you want to wait until the 
physical keyboard is free to make the bond or 1 if you want the 
function to return immediately. hkbd contains the keyboard handle. 
KbdGetFocus returns one of the following values: 


0 NO ERROR 


439 EREOR KBD INVALID HANDLE 
446 ERROR -KBD -FOCUS AiREADY ACTIVE 
447 ERROR-KBD-KEYBOARD BUS-Y 
464 ERRO R-KBD-DETACHED 
504 ERROR-KBD-EXTENDED SG 


The KbdGetstatus function returns the attached keyboard's 
hardware generated identification value. pkbdHwl D contains the 
hardware identification structure. hkbd contains the keyboard 
handle. The hardware identification structure contains the following 
entries: 


Offset Length Description 


Ooh 2 Length of the structure. 


Table 4-5 Continued 


Function 


FAPI, XPM 
Ushort 
KbdGetstatus 
(pkbdlnfo, hkbd) 


Description 


Offset I+ength Description 


02h 2 Keyboard identification number. This includes 


the following values: undefined (0000h), PC AT 
standard keyboard (0001h), 101-or 102-key 
enhanced (A841h), 88- or 89-key enhanced 
(A854h), or 122-key enhanced (A885h). 


04h 2 Reserved, set this field to o. 


06h 2 Reserved, set this field to o. 


KbdGetHWID returns one of the following values: 


0 NO ERROR 


373 ERffoR KBD PARAMETER 
447 ERROR-KBD-KEYBOARD BUSY 
4 6 4 ERRO R-KBD-DETACHED 
504 ERROR-KBD-EXTENDED SG 


The KbdGetstatus function returns the current keyboard status. 
FAPI applications ignore the keyboard handle value and always 
return a NULL value for NLS shift state. pkbdlnfo contains the 
keyboard information structure. hkbd contains the keyboard 
handle. The pkbd I nfo structure contains the following elements: 
Offset Length Description 


Ooh 2 Length of the structure (10 is the only valid 


value). 


02h 2 The mask information bits include: echo on (0), 


echo off (1), binary mode on (2), ASCII mode 
on (3), shift state modified (4), interim character 
flags modified (5), turnaround character 
modified (6), turnaround character length (7), 
shift return on (8), and reserved (9 through 15). 


04h2 


06h2 


08h2 


Definition of the turnaround character in ASCII 
and extended ASCII format. The turnaround 
character is the carriage return. 


The interim character flag bits include: reserved 
(0 through 4), application requested immediate 
conversion (5), reserved (6), interim character 
flag on (7), and NLS shift state (8 through 15). 


Shift state (see Kbdcharln). 


KbdGetstatus returns one of the following values: 


0 NO ERROR 


376 EREOR KBD INVALID LENGTH 


Function 


XPM 
Ushort Kbdopen 
(phkbd) 


FAPI, XPM 
Ushort Kbdpeek 
(pkbci, hkbd) 


XWPM 
Ushort KbdBegister 
(pszModName, 
pszEntrypt, 
fFunMask) 


Description 


439 ERROR KBD INVALID HANDLE 
445 ERROR=KBD=FO CUS_REQ UIRED 
447 ERROR KBD KEYBOARD BUSY 
4 6 4 ERROR-KBD-DETACHED 
504 ERROR-KBD-EXTENDED SG 


The Kbdopen function creates a new logical keyboard. Phkbd 
contains a pointer to the keyboard handle. Kbdopen returns one 
of the following values: 


0 NO ERROR 


440 EREOR KBD NO MORE HANDLE 
441 ERROR-KBD-CANNOT CREATE KCB 
4 64 ERROR-KBD-DETACHE-D 
504 ERROR-KBD-EXTENDED SG 


The Kbdpeek function returns any available character record data 
from the keyboard without removing it from the buffer. You must 
make two calls to this function to return DBCS (double-dyte character 
codes). If you set the shift report with Kbdsetstatus, then this 
function returns only the changed shift status information. The 
CharData structure does not include the time stamp when you use 
this function within a EAPI application. pkbci contains the character 
data information structure (see Kbdcharln for details). hkbd contains 
the keyboard handle. Kbdpeek returns one of the following values: 


0 NO ERROR 


439 EREOR KBD INVALID HANDLE 
445 ERROR=KBD=FO CUS_REQUIRED 
447 ERROR KBD KEYBOARD BUSY 
4 6 4 ERROR-KBD-DETACHED 
504 ERROR-KBD-EXTENDED SG 


The KbdRegister function registers a keyboard subsystem within a 
session. You can have one pending KbdRegister function pending 
at a time. pszModName contains the dynamic link module name. 
name. pszEntrypt contains the entry point routine name that 
receives control when you call any of the registered functions. 
fFunMax contains the following registration bits: Kbdcharln (0), 
Kbdpeek (1), KbdFlushRegister (2), KbdGetstatus (3), Kbdsetstatus 
(4), Kbdstringln (5), Kbdopen (6), Kbdclose (7), KbdGetFocus (8), 
KbdFreeFocus (9), KdbGetcp (10), Kbdsetcp (11), Kbdxlate (12), 
Kbdsetcustxt (13), KbdGetHWID (14), and reserved (15 through 
31). KbdRegister returns one of the following values: 


0 NO ERROR 


408 ERfroR KBD INVALID Ascllz 
4 0 9 ERROR-KBD-INVALID-MASK 
410 ERRO R-KBD-REGISTE-R 
46 4 ERROR-KBD-DETACHED 
504 ERROR-KBD-EXTENDED SG 


Table 4-5 Continued 


Function 


XPM 
Ushort Kbdsetcp 
(usBeserved, 
pidcp, hkbd) 


XPM 
Ushort Kbdsetcustxt 
(uscodepage, 
hkbd) 


XPM 
Ushort KbdsetFgnd 
(VOID) 


FAPI, XPM 
Ushort Kbdsetstatus 
(pkbdlnfo, hkbd) 


Description 


The Kbdsetcp function sets the code page used to translate scan 
codes into ASCII characters. usBeserved is a reserved parameter, 
set it to 0. pidcp contains the code page identifier. Common code 
page values include: 0 (resident code page), 437 (IBM PC US), 850 
(multilingual), 860 (Portuguese), 863 (Canadian-French), and 865 
(Nordic). hkbd contains the keyboard handle. Kbdsetcp returns 
one of the following values: 


0 NO ERROR 


375 EREOR KBD INVALID IOWAIT 
4 3 9 ERROR-KBD-INVALID-HANDLE 
445 ERROR=KBD=FO CUS_REQ UIRED 
447 ERROR KBD KEYBOARD BUSY 
4 6 4 ERROR-RED-DETACH ED 
504 ERROR-KBD-EXTENDED SG 


The Kbdsetcustxt function sets the translate table for the specified 
keyboard handle. uscodepage contains a pointer to the translation 
table used to translate a scan code to an ASCII character (see 
Category 4 Function Ox0050 of Table 4-4 for further details). hkbd 
contains the keyboard handle. Kbdsetcustxt returns one of the 
following values: 


0 NO ERROR 


377 EREOR KBD INVALID ECHO MASK 
3 7 8 ERRO R-KBD-INVALID-INPUT-MASK 
4 3 9 ERRO R-KBD-INVALID-HANDLE 
44 5 ERROR=KBD=FO CUS_REQ UIRED 
447 ERROR KBD KEYBOARD BUSY 
4 6 4 ERRO R-KBD-DETACH ED 
504 ERROR-KBD-EXTENDED SG 


The KbdsetFgnd increases the priority of the foreground keyboard's 
thread. KbdsetFgnd returns one of the following values: 


0 NO ERROR 


447 EREOR KBD KEYBOARD BUSY 
5 04 ERROR-KBD-EXTENDED -SG 


The Kbdsetstatus function sets the keyboard characteristics. FAPI 
applications ignore the keyboard handle value. They do not support 
the interim or turnaround character. pkbd I nfo contains the 
keyboard information structure (see Kbdsetstatus for further 
details). hkbd contains the keyboard handle. Kbdsetstatus returns 
one of the following values: 


0 NO ERROR 


376 EREOR KBD INVALID LENGTH 


Function 


FAPI, XPM 
Ushort 
Kbdstringln (pch, 
pchln, fswait, hkbd) 


XWPM 
Ushort 
Kbdsynch (fswait) 


XPM 
Ushort Kbdxlate 
(pkbdTrans, hkbd) 


Description 


::; :::3::K::::1%:::::N:P#iA:k 
445 ERRO R-KBD=FO CUS_REQ UIRED 
447 ERROR-RED KEYBOARD BUSY 
4 64 ERRO R-KBD-DETACHED 
504 ERROR-RED-EXTENDED SG 


The Kbdstringln function returns a character string from the 
keyboard. You can echo the character string to the display by 
setting echo mode. OS/2 does not allow you to use echo mode 
with binary mode. The default input mode is ASCII. FAPI 
applications do not need to supply a keyboard handle. pch contains 
a pointer to the character string buffer. pchln contains a pointer to 
the character string length (maximum length of 255). Template 
processing (meaningful in ASCII mode) returns two fields: cb (the 
length of the input buffer) and cchln (the number of dytes read into 
the buffer). fswait contains 0 if you want the function to wait for a 
character; otherwise, it contains 1 (no wait). hkbd contains the 
keyboard handle. Kbdstringln returns one of the following values: 


0 NO ERROR 


375 EREOR KBD INVALID IOWAIT 
43 9 ERROR-KBD-INVALID-HAND LE 
44 5 ERRO R-KBD=FO CUS_REQ UIRED 
447 ERROR-KBD KEYBOARD BUSY 
46 4 ERRO R-KBD-DETACHED 
504 ERROR-KBD-EXTENDED SG 


The Kbdsynch function synchronizes the keyboard subsystem to 
the keyboard device driver. This function blocks all other threads in 
a session until it returns from the subsystem to the router. fswait 
contains 0 if you do not want to wait for access to the device driver. 
Kbdsynch returns one of the following values: 


0 NO ERROR 


121 EREOR SEM TIMEOUT 


The Kbdxlate function translates scan codes with shift states into 
ASCII characters. You might need to call this function several times 
to complete a translation because of accent key combinations or 
other complexities. pkbdTrans contains the address of the 
translation record structure. hkbd contains the keyboard handle. 
The translation record structure contains the following elements: 
Offset I+ength Description 


00h 
2 See the KbdDDFlagword call in the ``Physical 


Keyboard Device Driver" section of the IBM 
OS/2 Technical Library Physical Device Driver 
Reference and Category 4 Functions Ox0074 
and Ox0079 in Table 4-4. 


Table 4-5 Continued 


Function 
Description 
Offset Length 
02h2 


04h2 


06h2 


Description 


The translation flag bits include: translation 
complete (0) and reserved (1 through 15). 


Translation state identification across calls. You 
can reset this entry to zero if you want to stop 
the current translation and start a new one. 


Translation state identification across calls. You 
can reset this entry to zero if you want to stop 
the current translation and start a new one. 


Kbdxlate returns one of the following values: 


0 NO ERROR 


439 EREOR KBD INVALID HANDLE 
445 ERRO R=KBD=FO CUS_REQ UIRED 
447 ERROR KBD KEYBOARD BUSY 
4 6 4 ERRO R-KBD-DETACH ED 
504 ERROR-KBD-EXTENDED SG 


MOU functions 


The MOU (mouse) functions help you create, delete, move, and 
change the mouse pointer. They also allow you to retrieve various 
pieces of information like the mouse pointer position and the number 
of mouse buttons. Of course, the DOSDevloctl functions offer most 
of the same features. The big difference is the flexibility of the 
DOSDevloctl functions versus the improved reporting and ease of 
use of the MOU functions. The actual difference between the two sets 
of functions is inconsequential in most cases. 


As with the KBD functions, OS/2 places restrictions on how and 
when you can use the MOU functions. There is at least one of the 
following three classifications assigned to each function. You can use 
FAPI functions in a family API application; a family API application 
runs equally well in DOS or OS/2. Presentation Manager will not 
allow you to use a XPM function within an application designed for 
that environment. However, you can use these functions in a 
windowed OS/2 character-mode session. A final restriction is that 


XWPM functions cannot appear in windowed OS/2 character-mode 
sessions; you must restrict their use to full-screen sessions only. 


The Borland compiler provides access to these functions through the 
BSESUB.H, BSEERR.H, and BSEDEV.H include files. The 
BSESUB.H file contains the function declarations. The BSEERR.H 
file contains all the error declarations. Finally, the BSEDEV.H file 
contains the constant declarations that you need to actually use the 
MOU functions. You might need to check the include files for your 
compiler to find references to these functions because most vendors 
do not document them. In some cases, the vendor uses a new name 
for the function. Fortunately, most vendors include a file with 
#defines that allow you to use the original names. 


IBM did not choose to document these functions after version 1.3 of 
OS/2 because they are machine specific and IBM plans to port OS/2 
to other platforms. The current OS/2 implementation encourages the 
developer to write to the less machine-specific Presentation Manager 
interface. You still can use all these functions within your current 
applications, but there is no guarantee that IBM will support them in 
future versions of OS/2. Use Presentation Manager specific functions 
whenever possible in your applications. 


Table 4-6 contains a complete listing of the MOU functions. 
Remember, these are the calls supported by OS/2 versions 1.3 and 
above. Versions before 1.3 might or might not support all the listed 
calls. Each entry contains the function classification, calling syntax, 
complete description, and any appropriate errors. It does not include 
any compiler specific calls supported by the Borland (or any other) 
compiler. 


MOU function listing 
Table 4-6 


Function 


XPM 
Ushort 
Mouclose (hmou) 


Description 


The Mouclose function closes the mouse device for the current 
session. hmou contains the mouse handle. Mouclose returns one 
of the following values: 


0 NO ERROR 


385 ERROR MOUSE NO DEVICE 
466 ERROR-MOu DETACHED 


Table 4-6 Continued 
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Function 


XWPM 
Ushort 
MouDeBegister 
(VOID) 


XPM 
Ushort 
MouDrawptr (hmou) 


XPM 
Ushort ) 
MouFlushQue 
(hmou) 


XPM 
Ushort 
MouGetDevstatus 
(pfsDevstatus, hmou) 


Description 


501 ERROR MOUSE NO CONSOLE 
505 ERROR-MOU EXTENDED SG 


The MouDeRegister function deregisters a mouse subsystem within 
a session. MouDeRegister returns one of the following values: 


0 NO ERROR 


385 ERROR MOUSE NO DEVICE 
416 ERROR-MOUSE-DEEEGISTER 
466 ERROR-MOU DETACHED 
505 ERROR-MOU-EXTENDED SG 


The MouDrawptr function notifies the mouse driver that a 
previously restricted area is free. This draws the pointer on the 
display. hmou contains the mouse handle. MouDrawptr returns one 
of the following values: 


0 NO ERROR 


385 ERROR MOUSE NO DEVICE 
466 ERROR-MOU DETACHED 
501 ERROR-MOUSE NO CONSOLE 
505 ERROR-MOU EkTENDED SG 


The MouFlushQue function empties the mouse event queue and 
monitor chain data for the session. hmou contains the mouse 
handle. MouFlushQue returns one of the following values: 


0 NO ERROR 


385 EREOR MOUSE NO DEVICE 
466 ERROR-MOU DETACHED 
501 ERROR-MOUSE NO CONSOLE 
505 ERROR-MOU EXTENDED SG 


The MouGetDevstatus function returns the status flags for the 
installed mouse device driver. pfsDevstatus contains a pointer to 
the device status flags. The status flag bits contain the following 
information: event queue busy with I/0 when set (0), block read in 
progress when set (1), flush in progress when set (2), pointer draw 
routine disabled by unsupported mode when set (3), reserved (4 
through 7), interrupt level pointer draw routine not called when set 
(8), mouse data returned in mickeys when set (9), and reserved (10 
through 15). hmou contains the mouse handle. MouGetDevstatus 
returns one of the following values: 


0 NO ERROR 


385 ERROR MOUSE NO DEVICE 
466 ERROR-MOU DETACHED 
501 ERROR-MOUSE NO CONSOLE 
505 ERROR-MOU EXTENDED SG 


Function 


XPM 
Ushort 
MouGetEventMask 
(pfsEvents, hmou) 


XPM 
Ushort 
MouGetNumButtons 
(pcButtons, hmou) 


XPM 
Ushort 
MouGetNumMickeys 
(pcMickeys, hmou) 


XPM 
Ushort 
MouGetNumQueEl 
(qmouQi, hmou) 


XPM 


Description 


The MouGetEventMask function returns the event queue mask. 
pfsEvents contains a pointer to the events mask structure. The 
event mask bits contain: all mouse motion (0), motion with button 1 
down (1), button 1 is down (2), motion with button 2 down (3), 
button 2 is down (4), motion with button 3 down (5), button 3 is 
down (6), and reserved (7 through 15). hmou contains the mouse 
handle. MouGetEventMask returns one of the following values: 


0 NO ERROR 


385 ERkoR MOUSE NO DEVICE 
466 ERROR-MOU DETACHED 
501 ERROR-MOUSE NO CONSOLE 
505 ERROR-MOu EXTEriDED SG 


The MouGetNumButtons function returns the number of buttons on 
the mouse. PCButtons contains the number of buttons (1 through 
3). hmou contains the mouse handle. MouGetNumButtons returns 
one of the following values: 


0 NO ERROR 


385 ERROR MOUSE NO DEVICE 
466 ERROR-MOU DETACHED 
501 ERROR-MOUSE NO CONSOLE 
505 ERROR-MOu EXTEriDED SG 


The MouGetNumMickeys function returns the number of mickeys in 
each centimeter for the installed mouse driver. pcMickeys contains 
the number of mickeys per centimeter. hmou contains the mouse 
handle. MouGetNumMickeys returns one of the following values: 


0 NO ERROR 


385 EREOR MOUSE NO DEVICE 
466 ERROR-MOu DETACHED 
501 ERROR-MOUSE NO CONSOLE 
505 ERROR-MOu EXTEriDED SG 


The MouGetNumQueEl function returns the number of mouse queue 
elements. qmouQi contains a pointer to the mouse queue status 
structure. This structure contains two fields: the number of event 
queue elements and the total number of elements available. hmou 
contains the mouse handle. MouGetNumQueEl returns one of the 
following values: 


0 NO ERROR 


385 ERfroR MOusE NO DEvlcE 
466 ERROR-MOu DETACHED 
501 ERROR-MOUSE NO CONSOLE 
505 ERROR-MOu EXTEriDED SG 


The MouGetptrpos function returns the mouse pointer coordinates. 


Table 4-6 Continued 


REffigivffiasRE. 


Function 


Ushort MouGetptrpos 
(pMouLoc, hmou) 


XPM 
Ushort 
MouGetptrshape 
(pBuf, pmoupslnfo, 
hmou) 


XPM 
Ushort 
MouGetscaleFact 
(pmouscFactors, 


Description 


pMouLoc contains the mouse location in two fields: row and column 
location in two fields: row and column. hmou contains the mouse 
handle. MouGetptrpos returns one of the following values: 


0 NO ERROR 


385 ERkoR MOUSE NO DEVICE 
466 ERROR-MOU DETACHED 
501 ERROR-MOUSE NO CONSOLE 
505 ERROR-MOU EXTENDED SG 


The MouGetptrshape function returns the pointer shape for the 
session. PBuf contains a pointer to a buffer used to hold the pointer 
information. If the buffer size is too small, the total length field of 
the pointer shape structure contains the actual size required. 
pmoupslnfo contains a pointer to the pointer shape structure. 
hmou contains the mouse handle. The pointer shape structure 
contains the following elements: 
Offset Length Description 


Ooh 2 Total length of the pointer buffer in bytes. The 


value for text modes is always 4. Use the 
following equation in graphics mode: total 
length = height in pels x width in pels x bits 
per pel x 2 / 8. 


02h 


04h 


06h 


O8h 


2 Number of columns in the mouse pointer 


shape. 


2 Number of rows in the mouse pointer shape. 


2 Column offset of the pointer hotspot within the 


mouse pointer shape. 


2 Row offset of the pointer hotspot within the 


mouse pointer shape. 


MouGetptrshape returns one of the following values: 


0 NO ERROR 


385 EREOR MOUSE NO DEVICE 
3 8 7 ERROR-MOUSE-INV-PARAMS 
466 ERROR-MOU DETACHED 
501 ERROR-MOUSE NO CONSOLE 
505 ERROR-MOU EXTENDED SG 


The MouGetscaleFact function returns the mouse scaling factors. 
pmouscFactors contains a pointer to the control block structure. 
This structure contains two fields: row Scale and colscale with 
values between 1 and (32K - 1). hmou contains the mouse handle. 


Function 


hmou) 


XWPM 
Ushort MoulnitBeal 
(pszDriverName) 


XPM 
Ushort Mouopen 
(pszDriverName, 
phmou) 


XPM 
Ushort 
MouBeadEventQue 
(pmouevEvent, 
pfwait, hmou) 


Description 


MouGetscaleFact returns one of the following values: 


0 NO ERROR 


385 ERROR MOUSE NO DEVICE 
466 ERROR-MOu DETACHED 
501 ERROR-MOUSE NO CONSOLE 
505 ERROR-MOU EXTENDED SG 


The MoulnitReal function initializes mouse support for DOS 
sessions. pszDriverName contains the name of the DOS mouse 
device driver. You must include this device driver name in 
CONFIG.SYS at startup time. Only the Base Video Subsystem 
should use this call. MoulnitReal returns one of the following values: 


0 NO ERROR 


385 EREOR MOUSE NO DEVICE 
412 ERROR-MOUSE-SM6 ONLY 
466 ERROR-MOU DETACHED 
501 ERROR-MOUSE NO CONSOLE 
505 ERROR-MOU EXTENDED SG 


The Mouopen function opens the mouse device for the current 
session. This initializes the mouse to a known state, but does not 
present the mouse pointer on screen. pszDriverName contains the 
ASCIIZ mouse device driver name. You must include this device 
driver name in CONFIG.SYS at startup time. Applications that use 
the default device driver should push a double word of zeros in 
place of the driver name address. phmou contains a pointer to the 
mouse handle. Mouopen returns one of the following values: 


0 NO ERROR 


385 ERfroR MOusE NO DEvlcE 
390 ERROR-MOUSE-INV-MODULE PT 
466 ERROR-MOU DETACHED 
501 ERROR-MOUSE NO CONSOLE 
505 ERROR-MOu EXTEriDED SG 


The MouReadEventQue function reads a mouse event from the FIFO 
queue and places it in the specified structure. pmouevEvent 
contains a pointer to the mouse event structure. pfwait contains 0 
if you want to return immediately even if the queue does not 
contain data. hmou contains the mouse handle. The mouse event 
structure contains the following elements: 
Offset I+ength Description 


Ooh 2 The event mask bits contain: all mouse motion 


(0), motion with button 1 down (1), button 1 is 
down (2), motion with button 2 down (3), 
button 2 is down (4), motion with button 3 
down (5), button 3 is down (6), and reserved (7 
through 15). hmou contains the mouse handle. 


Table 4-6 
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Function 


XWPM 
Ushort 
MouBegister 
(pszModName, 
pszEntryName, 
flFuncs) 


XPM 
Ushort 
MouBemoveptr 
(pmourtBect, hmou) 


Description 
02h4 


06h2 


08h2 


Time stamp in milliseconds since the user 
started the system. 


Mouse row position in absolute or relative 
coordinates. 


Mouse column position in absolute or relative 
coordinates. 


MouReadEventQue returns one of the fonowing values: 


0 NO ERROR 


385 EREOR MOUSE NO DEVICE 
3 8 7 ERROR-MOUSE-INV-PARMS 
3 9 3 ERROR-MOUSE-NO -DATA 
466 ERROR-MOU DETACHED 
501 ERROR-MOUSE NO CONSOLE 
505 ERROR-MOu EXTEriDED SG 


The MouRegister function registers a mouse subsystem within a 
session. Each session can have one open MouRegister. 
pszModName contains the dynamic link module name. 
pszEntryName contains the name of the routine that receives 
control when the application calls any of the registered functions. 
flFuncs contains a mask of bits that determine which functions the 
mouse routine handles. These function bits include: 
MouGetNumButtons (0), MouGetNumMickeys (1), MouGetDevstatus 
(2), MouGetNumQueE1 (3), MouReadEventQue (4), MouGetscaleFact 
(5), MouGetEventMask (6), MousetscaleFact (7), MousetEventMask 
(8), reserved (9 and 10), Mouopen (11), Mouclose (12), 
MouGetptrshape (13), Mousetptrshape (14), MouDrawptr (15), 
MouRemoveptr (16), MouGetptrpos (17), Mousetptrpos (18), 
MoulnitReal (19), MousetDevstatus (20), reserved (21 through 31). 
MouRegister returns one of the following values: 


0 NO ERROR 


385 EREOR MOUSE NO DEVICE 
413 ERROR-MOUSE-INVALID ASCII 
414 ERRO R-M OUSE-INVALID-MASK 
415 ERROR-MOUSE-REGISTE-R 
466 ERROR-MOU DETACHED 
505 ERROR-MOU-EXTENDED SG 


The MouRemoveptr function prevents the mouse driver from 
drawing the mouse pointer in the specified area. This area becomes 
the collision area. OS/2 allows only one active collision area at a 
time. pmourtBect contains a pointer to the pointer shape collision 
structure. hmou contains the mouse handle. The pointer shape 
collision structure contains the following elements: 


Function 


XPM 
Ushort 
MousetDevstatus 
(pfsDevstatus, 
hmou) 


XPM 
Ushort 
MousetEventMask 
(pfsEvents, hmou) 


XPM 
Ushort Mousetptrpos 
(pMouLoc, hmou) 


Description 
Offset Length Description 


Ooh 2 Upper-left row coordinate. 


02h 2 Upper-left column coordinate. 


04h 2 Lower-right row coordinate. 


06h 2 Lower-right column coordinate. 


MouRemoveptr returns one of the following values: 


0 NO ERROR 


385 EREOR MOUSE NO DEVICE 
38 7 ERROR-MOUSE-INV-PARMS 
466 ERROR-MOU DETACHED 
501 ERROR-MOUSE NO CONSOLE 
505 ERROR-MOu EXTEriDED SG 


The MousetDevstatus function sets the mouse device driver status 
flags. pfsDevstatus contains the status flags. These flags include: 
reserved (0 through 7), disable drawing operations for the drawing 
routine when set (8), return data in mickeys when set (9), and 
reserved (10 through 15). hmou contains the mouse handle. 
MousetDevstatus returns one of the following values: 


0 NO ERROR 


385 EREOR MOUSE NO DEVICE 
38 7 ERROR-MOUSE-INV-PARMS 
466 ERROR-MOU DETACHED 
501 ERROR-MOUSE NO CONSOLE 
505 ERROR-MOu EXTEriDED SG 


The MousetEventMask function sets the mouse event mask for the 
current mouse driver. pfsEvents contains the event mask (see 
MouGetEventMask for further details). hmou contains the mouse 
handle. MousetEventMask returns one of the following values: 


0 NO ERROR 


385 ERkoR MOUSE NO DEVICE 
466 ERROR-MOU DETACHED 
501 ERROR-MOUSE NO CONSOLE 
505 ERROR-MOu EXTEriDED SG 


The MousetptrLoc function sets the mouse pointer position on 
screen. pMouLoc contains a pointer to a structure containing two 
fields: row (the new mouse pointer row) and column (the new 
mouse pointer column). This function does not affect any collision 
areas. hmou contains the mouse handle. Mousetptrpos returns one 
of the following values: 


0 NO ERROR 


385 EREOR MOUSE NO DEVICE 
38 7 ERROR-MOUSE-INV-PARMS 


Table 4-6 Continued 


Function 


XPM 
Ushort 
Mousetptrshape 
(pBuf, pmoupslnfo, 
hmou) 


XPM 
Ushort 
MousetscaleFact 
(pmouscFact, hmou) 


XWPM 
Ushort 
Mousynch (iowait) 


Description 


466 ERROR MOU DETACHED 
501 ERROR-MOUSE NO CONSOLE 
505 ERROR-MOu EXTEriDED SG 


The Mousetptrshape function sets the mouse pointer shape and 
size. It affects all applications within a session. pBuf contains the 
address of a buffer holding the AND XOR pointer masks. 
pmoupslnfo contains a pointer to the mouse pointer strucutre (see 
MouGetptrshape for further details). hmou contains the mouse 
handle. Mousetptrshape returns one of the following values: 


0 NO ERROR 


385 ERffoR MOUSE NO DEVICE 
3 8 7 ERROR-MOUSE-INV-PARMS 
466 ERROR-MOU DETAC-HED 
501 ERROR-MOUSE NO CONSOLE 
505 ERROR-MOu EXTEriDED SG 


The MousetscaleFact function assigns new scaling factors to the 
current mouse driver. pmouscFact contains two fields:rowscale 
and colscale. Each field can contain a value from 0 to (32K-1). 
The default rowscale value is 16 mickeys for 8 pixels. The default 
colscale value is 8 mickeys for 8 pixels. hmou contains the mouse 
handle. MousetscaleFact returns one of the following values: 


0 NO ERROR 


385 ERROR MOUSE NO DEVICE 
3 8 7 ERROR-MOUSE-INV-PARMS 
466 ERROR-MOU DETAC-HED 
501 ERROR-MOUSE NO CONSOLE 
505 ERROR-MOu EXTEriDED SG 


The Mousynch function synchronizes the mouse subsystem to the 
current mouse driver. iowait determines if the function waits for 
access to the mouse driver. A value of 0 causes the function to 
return immediately. Mousynch returns one of the following values: 


0 NO ERROR 


121 ERffoR SEM TIMEOUT 


maREffimaffiffimaRE 


VERYONE knows that you need to perform some amount of 
magic to make the serial port work efficiently and without 


error under OS/2. Few might realize that you can even do very much 
with the parallel port-especially when it comes to printers. (Of 
course, you need to do some work to make the parallel port function 
with file transfer software, but this is another issue.) OS/2 provides 
you with the capability to work with both types of ports and optimize 
their use in your applications. It does require a little more low-level 
work that you might want to perform, but the capability does exist. 


This chapter assumes that you want to write a low-level routine that 
might or might not appear as part of an application. There is one 
section for each port type. The DOSDevloctl function is a low-level 
routine that assumes the reader requires very low-level access to the 
port. This usually happens when the developer needs to create a 
device driver or other ring 2 application. However, they are equally 
useful in standard applications. 


Use of the DOSDevloctl function appe\ars in chapter 4. Refer to that 
chapter for instructions on using this function before you try to use 
the material that appears in the following paragraphs. This function 
is very powerful, but it does sidestep many of the mechanisms that 
you normally would use within a windowed environment. 


Parallel and serial port 
DOSDevloctl functions 


OS/2 provides a number of default device driver functions that you can 
access using the DOSDevloctl function. The printer and serial port 
functions make up only a part of the things that you can access. Many 
texts refer to the printer functions as PRT (for print) calls. Likewise, the 
serial port calls use an ASYNC (asynchronous communication) prefix. 
Your specific computer configuration might provide even more than 
you see here. For example, parallel ports in newer machines provide 
bidirectional data transfer. Given the right kind of device driver, you 
could use this capability to create a file transfer program. Newer serial 
ports provide hardware buffers that you could use to improve 
communication program performance in some situations. The right 


kind of device driver would make this activity much easier. As you can 
see, it pays to fully explore the capabilities of your system and those of 
others you create programs for. 


The following paragraphs concentrate on the generic printer and 
serial port functions, but it always pays to search the vendor 
documentation and the INI files on your system. You might want to 
check the device drivers themselves for additional information 
(provided the software licensing agreement does not prevent this 
action). Some vendors might even sell a developer's kit or other form 
of formal documentation for their device driver. 


The Borland compiler provides access to the PRT functions through 
the BSEDEV.H and BSEDOS.H include files. The BSEDEV.H file 
contains the entries that you need to actually use the DOSDevloctl 
function. The BSEDOS.H file contains the DOSDevloctl function 
declaration. Both files provide interesting bits of information. You 
might need to check the include files for your compiler to find 
references to these functions because most vendors do not document 
them. In some cases, the vendor uses a new name for the function. 
Fortunately, most vendors include a file with #defines that allow you 
to use the original names. Table 5-1 provides a complete list of the 
printer and serial port DOSDevloctl functions. 


OS/2 Version 1.0 and 1.1 device drivers do not understand generic 
IOctl packets. As a result, the kernel does not pass the 
ulDataLengthMax, pDataLengthlnout, ulparmLengthMax, and 
pparmLengthlnout parameters to the device driver. You must 
mark device drivers level 2 or higher to support receipt of these fields. 


DOSDevl0Ctl printer and serial port generic functions 


Function Name Description 


Parallel Port IOctl Commands (Category 5) 


Ox0042 Set Frame 


Control 


This function sets the frame control. The parameter 
information includes command information (BYTE). This is a 
reserved field; set it to 0. The data information includes: 
characters per line (80 and 132) and lines per inch (6 and 8). 
This function returns the following error codes: 


Table 5-1 Continued 


Function Name 


Ox0044 Set Infinite 


Retry 


Ox0046 


Ox0048 


Initialize 
Parallel Port 


Activate 
Font 


Description 


OxO100 Completed successfully 
Ox8102 Device not ready 
Ox8103 Invalid command 
Ox810A Write fault 


This function sets infinite retry. It is always enabled when 
there is a monitor registered for the physical Parallel Port 
device driver. A disable request returns a good return code 
when you have a monitor registered even though the function 
does not do anything. The parameter information includes 
command information (BYTE). This is a reserved field; set it to 
0. The data information contains infinite retry field (0 for 
disable and 1 for enable) (BYTE). This function returns the 
following error codes. 


OxO100 Completed successfully 
Ox8103 Invalid command 


This function initializes the parallel port; setting it to a known 
state. The parameter information includes command 
information (BYTE). This is a reserved field; set it to 0. The 
data information includes a reserved field (BYTE). This 
function returns the following error codes. 


OxO100 Completed successfully 
Ox810A Write fault 


This function activates a particular printer font. You need to 
know the font capabilities of your printer to use cartridge 
capability provided by this function. The parameter 
information includes command information (BYTE). This is a 
reserved field; set it to 0. The data information includes: code 
page (WORD) and font identification (WORD). Using a value 
of 0 for the code page and font identification sets the printer 
to its default code page and font. The valid range of code page 
values includes OxOoo 1 to OxFFFF. The font identification 
range is OxOool to OxFFFF. You can select a cartridge by 
sending the identification number appearing on the cartridge 
to the printer. The cartridge number must appear in the 
DEVINFO statement for the printer. This function returns the 
following error codes: 


OxO100 Completed successfully 
Ox810A Write fault 
OxC102 Code page not available 
OxC103 No code page available (spooler not started) 
OxC104 Font ID not available 


Function Name 


Ox004D 


Ox004E 


Ox0062 


Ox0064 


Set Print 
Job Title 


Set Parallel 
Port IRQ 
Timeout 
Value 


Query 
Frame 
Control 


Query 
Infinite Retry 


Description 


OxC109 Error caused by switcher error 
OxC10A Error caused by invalid printer name 
OxC10D Code page switcher uninitialized 
OxC10F SFN table full 
OxC113 DASD error reading font file 
OxC115 DASD error reading font file definition block 
OxC117 DASD error while writing spool file 
OxC118 Disk full error while writing spool file 
OxC119 Bad spool file handle 


This function sets the print job title. ASCII strings longer than 
126 characters get truncated to 125 characters plus the null 
character. The parameter information includes command 
information (BYTE). This is a reserved field; set it to 0. The 
data information includes: buffer length of the print job title 
(WORD) and the address of the ASCIIZ string containing the 
print job title (DWORD). This function returns the following 
error codes: 


OxO100 Completed successfully 
Ox8113 Invalid parameter 


This function sets the parallel IRQ timeout value. This is the 
length in time that the printer driver waits for a printer IRQ 
before it cancels the print job. The valid timeout range is 0 to 
65,535 seconds. You also must issue a Prfwriteprofilestring 
to update the OS2SYS.INI file when changing this value. The 
parameter information includes command information (BYTE). 
This is a reserved field; set it to 0. The data information 
includes the timeout value in seconds (WORD). This function 
returns the following error codes: 


OxO100 Completed successfully 
Ox8113 Invalid parameter 


This function returns the current number of print columns 
and rows. The parameter information includes command 
information (BYTE). This is a reserved field; set it to 0. The 
data information includes: characters per line (80 and 132) 
and lines per inch (6 and 8). This function returns the 
following error code: 


OxO100 Completed successfully 


This function returns the infinite retry status. The parameter 
information includes command information (BYTE). This is a 
reserved field; set it to 0. The data information contains 
infinite retry field (0 for disable and 1 for enable) (BYTE). This 
function returns the following error code: 


OxO100 Completed successfully 
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Function Name 


Ox0066 Query 


Parallel 
Port Status 


Ox0069 
Query 
Active Font 


Description 


This function returns the parallel port status. The parameter 
information includes command information (BYTE). This is a 
reserved field; set it to 0. The data information contains the 
port data field. The port data field includes the following bits: 
timeout (0), reserved (1 and 2), I/0 error (3), selected (4), 
out-of-paper (5), acknowledge (6) and not busy (7). This 
function returns the following error code: 


OxO100 Completed successfully 


This function returns the active font identification and code 
page information. The parameter information includes 
command information (BYTE). This is a reserved field; set it 
to 0. The data information includes: code page (WORD) and 
font identification (WORD). The valid range of code page 
values includes OxOool to OxFFFF. The font identification 
range is OxOool to OxFFFF. This function returns the 
following error codes: 


OxO100 Completed successfully 
OxC103 No code page available (spooler not started) 
OxC109 Error caused by switcher error 
OxC10A Error caused by invalid printer name 
OxC10D Code page switcher uninitialized 
OxC110 Received request for SFN not in SFN table 


Ox006A Verify Font This function verifies the availability of a particular font 


identification and code page for the specified printer. The 
parameter information includes command information 
(BYTE). This is a reserved field; set it to 0. The data 
information includes: code page (WORD) and font 
identification (WORD). Using a value of 0 for the code page 
and font identification requests the printer's default code 
page and font; this combination is always available. The valid 
range of code page values includes OxOool to OxFFFF. The 
font identification range is OxOool to OxFFFF. You can select 
a cartridge by sending the identification number appearing 
on the cartridge to the printer. The cartridge number must 
appear in the DEVINFO statement for the printer. This 
function returns the following error codes: 


OxO100 Completed successfully 
OxC102 Code page not available 
OxC103 No code page available (spooler not started) 
OxC104 Font ID not available 
OxC10A Error caused by invalid printer name 
OxC10D Code page switcher uninitialized 


Function Name 


Ox006E Query 


Parallel Port 
IRQ Timeout 
Value 


Description 


This function returns the parallel IRQ timeout value. This is 
the length in time that the printer driver waits for a printer 
IRQ before it cancels the print job. The valid timeout range is 
0 to 65,535 seconds. The parameter information includes 
command information (BYTE). This is a reserved field; set it 
to 0. The data information includes the timeout value in 
seconds (WORD). This function returns the following error 
codes: 


OxO100 Completed successfully 
Ox8113 Invalid parameter 


Serial Port (RS232-C) IOctl Commands (Category 1) 


Ox0041 Set Bit Rate 


Ox0042 


Ox0043 


Set Line 
Characteristics 


Extended 
Set Bit Rate 


This function sets the bit rate. An OPEN request packet will 
not change the value that you set with this function. The 
default bit rate is 1200 bps. You can use values from 2 bps to 
19200 on conventional serial devices and from 10 bps to 
57,600 bps on enhanced serial devices. The parameter 
information includes the bit rate (WORD). The hardware 
must support any bit rate you request up to 19,200 bps with 
a 0.010/o margin of error (110 bps uses 0.0260/o and 2000 
bps uses 0.690/o). The device driver does not check the 
tolerance for bit rates above 19,200 bps. Use function 
Ox0061 to check the actual bit rate if you set the bit rate 
above 19,200 bps. There is no data information. This 
function returns a general failure if it does not succeed. 


This function sets the serial port parameters. An OPEN 
request packet will not change the characteristics that you set 
with this function. The physical device driver automatically 
zeros the data high bits if you set the word length to less than 
8 bits. Your application must ensure that this does not 
conflict with any control sequence characters required to 
maintain flow control or other control sequences. The 
parameter information includes: number of data bits (BYTE), 
parity (BYTE), and stop bits (BYTE). The range of the data 
bits field is 5 to 8 data bits. The parity field contains the 
following information: no parity (00h), odd parity (01h), even 
parity (default) (02h), mark parity (03h), space parity (04h), 
and reserved (05h to FFh). The stop bits field contains the 
following values: 1 stop bit (00h),1.5 stop bits (01h), 2 stop 
bits (02h), and reserved (03h to FFh). There is no data 
information. This function returns a general failure if it does 
not succeed. 


This function sets the bit rate in DWORDs to cover bit rates 
higher than 19,200 bps. It is an extension of function 
Ox0041. The parameter information includes: bit rate in bps 
(DWORD) and fraction (BYTE). The bit rate range for 
enhanced UARTs is 10 bps to 345,600 bps. Use function 


Table 5-1 
Continued 


Function Name 


Ox0 044 Transmit 


Byte 
Immediate 


Ox0045 


Ox0046 


Set Break 
OFF 


Set MODEM 
Control 
Signals 


Description 


Ox0063 to determine the maximum bit rate supported by the 
hardware. 


The fraction field allows you to set very precise bit rates (the 
default setting for this field is 0). Determine the value that 
you need for this field using the following equation: Output 
Bit Rate = Baud Clock / Scalar / Divisor Count; then 
multiply the fractional portion of Output Bit Rate x 256. The 
baud clock for an enhanced chip is 22.1184 MHz. The 
scalar value is 32. You can determine the divisor count using 
the following equation: Divisor Count = Baud Clock / Scalar 
/ Binary Bit Rate. A shortcut for this whole procedure is to 
multiply the fractional portion of the desired baud rate by 
256. For example, if you wanted to set the baud rate to 
19,200.5 bps, then you would multiply 0.5 x 256 and set 
fraction to 128. The hardware must support any bit rate that 
you request up to 19,200 bps with a 0.01°/o margin of error 
(110 bps uses 0.0260/o and 2000 bps uses 0.690/o). The 
device driver does not check the tolerance for bit rates above 
19,200 bps. Use function Ox0063 to check the actual hit 
rate if you set the bit rate above 19,200 bps. There is no 
data information. This function returns a general failure if it 
does not succeed. 


This function transmits a byte immediately. The function fails 
if there is already a character in the physical device queue. 
You can determine if this condition exists using function 
Ox0064. The parameter information includes the character 
you want to transmit (BYTE). There is no data information. 
This function returns a general failure if it does not succeed. 


This function forces the physical device driver to stop 
generating a break signal. There is no parameter 
information. The data information includes a 
communications error word (WORD). The physical device 
driver returns this information if the call does not generate an 
error (see function Ox006D for full details). This function 
returns a general failure if it does not succeed. 


This function sets the MODEM control signals. The 
parameter information includes: MODEM control signals ON 
mask (BYTE) and MODEM control signals OFF mask 
(BYTE). Attempting to set the same bit in both masks always 
results in a general error. Both masks use the following bits: 
DTR (0), RTS (1), and reserved (2 through 7). You set a 
control signal on using a 1 in the ON mask. You set a control 
signal off using a 0 in the OFF mask. For example, to set 
DTR, you would use a value of Olh in the ON mask and FFh 


Function Name 


Ox0047 


Ox0048 


Ox004B 


Ox0053 


Behave as 
if XOFF 
Received 


Behave as 
if XON 
Received 


Set Break 
On 


Set DCB 
Parameters 


Description 


in the OFF mask. To clear DTR, you would use a value of 
Ooh in the ON mask and a value of FEh in the OFF mask. 
The data information includes a communications error word 
(WORD). The physical device driver returns this information 
if the call does not generate an error (see function Ox006D 
for full details). This function returns a general failure if it 
does not succeed. 


This function causes the physical device driver to act as if it 
received an XOFF character if you enable automatic transmit 
flow control. It causes a general failure error if the reception 
of the XOFF character causes the data transmission to stop. 
There is no parameter or data information. This function 
returns a general failure if it does not succeed. 


This function causes the physical device driver to act as if it 
received an XON character. There is no parameter or data 
information. This function returns a general failure if it does 
not succeed. 


This function sets break ON. If this does not result in a 
general failure, the physical device driver immediately 
generates a break signal. The transmit hardware does not 
receive any more data until you set break OFF. There is no 
parameter information. The data information includes a 
communications error word (WORD). The physical device 
driver returns this information if the call does not generate an 
error (see function Ox006D for full details). This function 
returns a general failure if it does not succeed. 


This function sets the device control block (DCB) information. 
The parameter information includes: zero-based write timeout 
processing interval in 0.01 second increments (WORD), zero- 
based read timeout processing interval in 0.01 second 
increments OvORD), Flagsl (BYTE), Flags2 (BYTE), Flags3 
(BYTE), error-replacement character (BYTE), break- 
replacement character (BYTE), XON character (BYTE), and 
XOFF character (BYTE). Flagsl contains: DTR control (0 and 
1), reserved (2), enable output handshaking using CTS (3), 
enable output handshaking using DSR (4), enable output 
handshaking using DCD (5), enable input sensitivity using 
DSR (6), and reserved (7). The DTR values include: disable 
(00b), enable (01b), input handshaking (lob), and invalid 
input (llb). Flags2 contains: enable automatic flow control 
(0), enable automatic receive flow control (1), reserved (2), 
enable error replacement character (3), enable break 
replacement character (4), enable receive flow control (5), and 
RTS control mode (6 and 7). The RTS values include: disable 
(00b), enable (01b), input handshaking (lob), and toggling on 
transmit (llb). Flags3 contains: enable write timeout 
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Function Name 


Ox0054 


Ox0061 


Ox0062 


Set Enhanced 
Enhanced 
Mode 
Parameters 


Query Bit 
Rate 


Query Line 
Characteristics 


Description 


processing (0), enable read timeout processing (1 and 2), 
extended hardware buffering (3 and 4), received trigger level 
(5 and 6), and transmit buffer load count (0 = 1 character and 
1 = 16 characters). The read timeout processing values 
include: invalid input (00b), normal read timeout processing 
(01b), and no-wait read timeout processing (lob or llb). The 
extended hardware buffering values include: not supported 
(00b), disabled (01b), enabled (lob), and automatic protocol 
override (llb). The received trigger level values include: 1 
character (00b), 4 characters (01b), 8 characters (lob), and 
14 characters (llb). There is no data information. This 
function returns a general failure if it does not succeed. 


This function sets the enhanced-mode parameters used by 
the enhanced UART on many machines. The physical device 
driver uses either the DMA or Enhanced FIFO mode as a 
default. In DMA mode, the DMA chip takes care of all 
transfers between memory and the port. Enhanced mode 
uses the full buffering capabilities of the extended hardware 
buffer. The parameter information includes: enhanced Flagsl 
(BYTE) and reserved (DWORD). Enhanced Flagsl bit 
structure contains: enhanced mode supported by hardware 
(0), enable enhanced mode (1), DMA receive operation 
request (2 and 3), DMA transmit operation request (4 and 5), 
receive operation in DMA mode (6), and transmit operation 
in DMA mode (7). The DMA receive operation request values 
include: disable (00b), enable (01b), dedicate a DMA channel 
to receive operation (lob), and reserved (llb). The DMA 
transmit operation values include: disable (00b), enable (01b), 
dedicate a DMA channel to transmit operation (lob), and 
reserved (llb). There is no data information. This function 
returns a general failure if it does not succeed. 


This function returns the current bit rate setting. If the current 
bit rate is greater than the value a 1-WORD field can hold, 
then the physical device driver sets the bit rate to 1200 and 
returns that value. There is no parameter information. The 
data information includes the bit rate in bps (bits per second) 
(WORD). This function returns a general failure if it does not 
succeed. 


This function returns the current line characteristics. There is 
no parameter information. The data information includes: 
number of data bits (BYTE), parity (BYTE), stop bits (BYTE), 
and transmitting break. The range of the data bits field is 5 to 
8 data bits. The parity field contains the following 
information: no parity (00h), odd parity (01h), even parity 


Function Name 


Ox0063 


Ox0064 


Ox0065 


Ox0066 


Extended 
Query 
Bit Rate 


Query 
COM Status 


Query 
Transmit 
Data Status 


Query 
MODEM 
Output 
Signals 


Description 


(default) (02h), mark parity (03h), space parity (04h), and 
reserved (05h to FFh). The stop bits field contains the 
following values: 1 stop bit (00h),1.5 stop bits (01h), 2 stop 
bits (02h), and reserved (03h to FFh). The function sets the 
transmitting break field to 0 if the physical device driver is not 
transmitting a break character. This function returns a general 
failure if it does not succeed. 


This function returns the bit rate in DWORDs to cover bit 
rates higher than 19,200 bps. It is an extension of function 
Ox0061. There is no parameter information. The data 
information includes: bit rate in bps (DWORD), fraction of 
current bit rate (BYTE), minimum bit rate supported in bps 
(DWORD), fraction of minimum bit rate supported (BYTE), 
maximum bit rate supported (DWORD), and fraction of 
maximum bit rate supported (BYTE). The bit rate range for 
enhanced UARTs is 10 bps to 345,600 bps. Factors 
including overall system overhead, the electrical 
characteristics of the hardware cables, and serial port type all 
affect the maximum bit rate supported value. This function 
returns a general failure if it does not succeed. 


This function returns the communications port status. There 
is no parameter information. The data information includes 
the COM status byte (BYTE). This status byte includes the 
following information: transmit status (Tx) waiting for CTS 
turn on (0), Tx waiting for DSR turn on (1), Tx waiting for 
DCD turn on (2), Tx waiting because XOFF received (3), Tx 
waiting because XOFF transmitted (4), Tx waiting because 
physical device driver is transmitting break character (5), 
character waiting to transmit immediately (6), and receive 
status (Rx) waiting for DSR turn on (7). This function returns 
a general failure if it does not succeed. 


This function returns the transmit data status. There is no 
parameter information. The data information includes the 
transmit status (BYTE). The transmit status field contains the 
following information: WRITE request packets in progress or 
queued (0), data in the physical device driver transmit queue 
(1), transmit hardware currently transmitting data (2), 
character waiting for immediate transmission (3), waiting to 
automatically transmit XON (4), waiting to automatically 
transmit XOFF (5), and undefined (6 and 7). This function 
returns a general failure if it does not succeed. 


This function returns the MODEM control output signals. 
There is no parameter information. The data information 
includes the MODEM control output signals (BYTE). This 
field contains the following information: DTR (0), RTS (1), 
and undefined (2 through 7). This function returns a general 
failure if it does not succeed. 
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Function Name 


Ox0067 


Ox0068 


Ox0069 


Ox006D 


Ox0072 


Query 
MODEM 
Input Signals 


Query 
Number of 
Characters in 
Receive 
Queue 


Query 
Number of 
Characters in 
Transmit 
Queue 


Query COM 
Error 


Query COM 
Event 
Information 


Description 


This function returns the current MODEM control input 
signals. There is no parameter information. The data 
information includes the MODEM control input signals 
(BYTE). This field contains the following information: 
undefined (0 through 3), CTS (4), DSR (5), RI (6), and DCD 
(7). This function returns a general failure if it does not 
succeed. 


This function returns the number of characters in the receive 
queue. There is no parameter packet information. The data 
information includes: number of characters queued (WORD) 
and size of receive queue (WORD). You cannot assume that 
there are no unsatisfied read requests if there are characters 
in the queue. The default queue size is lK in Plo mode and 
2K in DMA mode. This function returns a general failure if it 
does not succeed. 


This function returns the number of characters in the transmit 
queue. There is no parameter packet information. The data 
information includes: number of characters queued (WORD) 
and size of transmit queue (WORD). You cannot assume that 
there are no unsatisfied write requests if there are characters 
in the queue. The default queue size is 128 bytes in Plo 
mode and 255 bytes in DMA mode. This function returns a 
general failure if it does not succeed. 
This function retrieves the COM device error information, 
then clears the COM error information buffer. There is no 
parameter information. The data information includes the 
COM error word (COMERR) (WORD). The physical device 
driver sets COMERR when any of the events listed for the bit 
field occur. Only this function or an OPEN call can clear 
the COMERR buffer. This field contains the following 
information: receive queue overrun (0), receive hardware 
overrun (1), hardware detected parity error (2), hardware 
detected framing error (3), and undefined (4 through 15). 
This function returns a general failure if it does not succeed. 


This function retrieves then clears the COM device event 
WORD. There is no parameter information. The data 
information includes the COM event word (WORD). The 
physical device driver sets the appropriate bits in the COM 
event word whenever one of the following events occur: 
character read from the COM device receive hardware and 
placed in the receive queue (0); serial port controller 
generated receive timeout interrupt during a receive request 
(1); last character in transmit queue set to the COM device 
transmit hardware (2); CTS changed state (3); DSR changed 


Function Name 


Ox0073 


Ox0074 


Query 
DCB 
Parameters 


Query 
Enhanced 
Mode 
Parameters 


Description 


state (4); DCD changed state (5); break detected (6); parity, 
framing, or receive hardware overrun (7); RI detected (8); and 
undefined (9 through 15). This function returns a general 
failure if it does not succeed. 


This function returns the device control block (DCB) 
information. There is no parameter information. The data 
information includes: zero-based write timeout processing 
interval in 0.01 second increments (WORD), zero-based read 
timeout processing interval in 0. 01 second increments (WORD), 
Flagsl (BYTE), Flags2 (BYTE), Flags3 (BYTE), error- 
replacement character (BYTE) , break~replacement character 
(BVIE), XON character (BVIE), and XOFF character (BVIE). 
Flagsl contains: DTR control (0 and 1), reserved (2), enable 
output handshaking using CTS (3) , enable output handshaking 
using DSR (4), enable output handshaking using DCD (5), 
enable input sensitivfty using DSR (6), and reserved (7). The 
DTR values include: disable (00b), enable (01b), input 
handshaking (lob), and invalid input (llb). Flags2 contains: 
enable automatic flow control (0), enable automatic receive flow 
control (1), reserved (2), enable error-replacement character (3), 
enable break-replacement character (4), enable receive flow 
control (5), and RTS control mode (6 and 7). The RTS values 
include: disable (00b), enable (01b), input handshaking (lob), 
and toggling on transmit (llb). Flags3 contains: enable write 
timeout processing (0), enable read timeout processing (1 and 
2), extended hardware buffering (3 and 4), received trigger level 
(5 and 6), and transmit buffer load count (0 = 1 character and 1 
= 16 characters). The read timeout processing values include: 
invalid input (00b), normal read timeout processing (01b), and 
no-wait read timeout processing (lob or llb). The extended 
hardware buffering values include: not supported (00b), disabled 
(01b), enabled (lob), and automatic protocol override (llb). 
The received trigger level values include: 1 character (00b), 4 
characters (01b), 8 characters (lob), and 14 characters (llb). 
This function returns a general failure if it does not succeed. 


This function returns the enhanced mode parameters used by 
the enhanced UART on many machines. The physical device 
driver uses either the DMA or Enhanced FIFO mode as a 
default. In DMA mode, the DMA chip takes care of all 
transfers between memory and the port. Enhanced mode 
uses the full buffering capabilities of the extended hardware 
buffer. There is no parameter information. The data 
information includes: enhanced Flagsl (BYTE) and reserved 
(DWORD). Enhanced Flagsl bit structure contains: enhanced 
mode supported by hardware (0), enable enhanced mode (1), 
DMA receive operation request (2 and 3), DMA transmit 
operation request (4 and 5), receive operation in DMA mode 
(6), and transmit operation in DMA mode (7). The DMA 
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Function Name 
Description 


(01b), dedicate a DMA channel to receive operation (lob), 
and reserved (llb). The DMA transmit operation values 
include: disable (00b), enable (01b), dedicate a DMA channel 
to transmit operation (lob), and reserved (llb). This function 
returns a general failure if it does not succeed. 


Using Table 5-1 is quite simple. The previous paragraphs describe the 
calling syntax for this function. You obtain hDevHandle using an open 
call. The ulcategory entry appears in the heading for each group of 
function calls. The ulFunction entry appears in the first column of the 
table. The rest of the entries (pparmList, ulparmLengthMax, 
pparmLengthlnout, pDataArea, ulDataLengthMax, and 
pDataLengthlnout) appear in the function description in chapter 4. You 
need to provide the specifics required to make these function work. 


Testing your printer application completely might require you to know 
a little about the parallel port itself . For example, wouldn't it be nice 
if you could test out some of your error trapping routines without 
spending too much time trying to get the printer to simulate the 
failure? You can build a small jig called a loopback plug to partially 
test your print application without wasting one sheet of paper. This is 
a parallel port plug that is wired in such a way that it fools the 
computer into thinking there is a printer attached to the machine. In 
reality, all you are doing is simulating a printer. Likewise, by removing 
one of the interconnection wires, you can simulate a printer failure. 
This allows you to check the response of your printer with the least 
potential for problems. Table 5-2 provides a complete listing of the 
interconnections required to create a loopback plug. Each connection 
has a signal name associated with it. All you need to do is disconnect 
the required connect to test a potential printer problem. 


Figure 5-1 


db25M 


Parallel port pinouts. 


Parallel port loopback plug connections 
Table 5-2 


From Connection 
11-Busy 
10-Acknowledge 
printer 
12-Paper out 
13-Select 
02-Data 0 


To Connection 
17-Select input 
16-Initialize 


14-Auto feed 
01-Strobe 
15-Error 


Many of the serial port functions listed in Table 5-1 use obscure looking 
acronyms. These acronyms come from the name of the signals that 
appear on the RS-232 port. Table 5-3 contains a complete list of all 
these acronyms along with their associated signal names. 


Serial port pinouts 
(Part 1). 


Serial port pinouts (Part 2). 


db9F 


Table 5-3 provides you with more than just a few acronyms and 
definitions. You can use a loopback plug to test the functions of a 
serial port in much the same way as you can with a parallel port. 
The parallel port uses a male plug while the serial port uses a 
female plug, but the test concept is the same. Table 5-3 provides 
you with a complete list of interconnections required to make 
either a 9-pin or 25-pin serial loopback plug. You probably will 
want to make at least one of each type to ensure you have the 
right testing plug for all occasions. 


You don't have to make these plugs yourself . There are many 
computer hardware supply stores that provide ready-made versions of 


Figure 5-2 


Figure 5-3 


Table 5-3 


these useful plugs since technicians also use them to test the 
computer's hardware. You also can order the plugs from Performance 
Computer Diagnostics, 703 Grand Central Street, Clearwater, FL 
34616, (813)443-1331. 


Serial port loopback plug connections 


From Connection 
db9F Connector 
02-Received data (RD) 
07-Request to send (RTS) 
06-Data set ready (DSR) and 
0 1-Carrier detect (CD) 


db25F Connector 
02-Received data (RD) 
04-Request to send (RTS) 
06-Data set ready (DSR) and 
08-Carrier detect (CD) 


To Connection 


03-Transmitted data (TD) 
08-Clear to send (CTS) 
04-Data terminal ready (DTR) and 
09-Ring indicator (RI) 


03-Transmitted data (TD) 
05-Clear to send (CTS) 
20-Data terminal ready (DTR) and 
22-Ring indicator (RI) 


EEREREffiREillfiEffi 


ORKING with the OS/2 disk interface can get rather 
confusing for the average programmer. The operating system 


makes it easy to access a disk as long as you know the disk 
parameters and what type of access that you require. It seems like an 
easy thing to do until you consider that there are more disks on the 
market than anyone probably realizes. Each one uses a different set 
of parameters and some complicate matters by using disk translation 
to work with obsolete BIOS chips. Add to this maze the plethora of 
available controllers, and you get a puzzle of astronomical 
proportions. As you can see, figuring out what type of access you 
need and how to get it isn't as easy as it might first appear. 


This chapter covers the three levels of support provided by OS/2 for 
disk operations. While it will not teach you everything there is to 
know about accessing hard disk drives, it does provide you with the 
OS/2 viewpoint. The first section tells you about the high-level disk 
specific functions provided by OS/2. The second section assumes the 
reader wants to create a Presentation Manager application. This is 
the section that covers OS/2's logical viewpoint of the disk. The third 
section is the disk operating system (or physical) level. Ring 2 and 
character-mode applications use this part of the API. 


There are a number of ``DOS" functions provided by OS/2. These 
functions usually provide you with high-level access that augments the 
access you gain using the WIN and GPI functions in chapter 3. 
(Remember, you can use a file as a device context in certain cases.) 
These functions appear in the first section of this chapter. Each 
description tells you about the function and how to use it. The 
descriptions also provide you with the ancillary information required 
to fully utilize the function in your applications. 


OS/2 also provides disk access through the DOSDevloctrl function (I 
covered how you can use this flexible function to access other devices 
in the previous two chapters). Unlike the previous two chapters, the 
disk interface complicates matters by providing two levels of control: 
logical and physical. 


DOsphvsicalDisk 


The DOsphysicalDisk function returns information about 
partitionable disks. The handle that you receive from the function 
allows you to access the drive using the DOSDevloctl function 
category 9 (logical disk access). You cannot use this handle for 
physical disk access. It uses the following syntax: 


rc = DOsphysicalDisk (ulFunction, pDataArea, ulDataLen, 


pparmList, ulparmLen) 


The function provides only one return value (it does provide some 
return parameters discussed in the following paragraphs). rc contains 
a return code that tells you whether the function completed without 
error. It also contains an error code if it didn't. Table 6-1 provides a 
list of these error codes. 


DOsphysicalDisk function return codes 


Error 
number Description 


0 NO ERROR 


1 ERROR INVALID FUNCTION 


87 ERROR INVALID PARAMETER 


There are five parameters for this function. ulFunction contains a 
device specific function code in the range from 0 to 255. There are 
three tasks that you can perform with this function: obtain the total 
number of partitionable disks (INFO_COUNT_PARTITIONABLE_DISKS 
or a value of 1), get a handle to use with category 9 DOSDevloctl 
calls (INFO_GETIOCTLHANDLE or a value of 2), or release a handle 
used with category 9 DOSDevloctl calls (INFO_FREEIOCTLHANDLE 
or a value of 3). pDataArea contains address of the buffer used to 
hold the data information. Table 6-2 contains a complete listing of 
the data required for each task. ulDataLen contains the length of 
pDataArea in bytes (see Table 6-2 for valid lengths). A NULL value 
for pDataArea tells OS/2 that there is no data information defined 
for this call. OS/2 automatically ignores the ulDataLen parameter. 


Table 6-2 


pparmList contains the address of the command-specific argument 
list. Table 6-3 contains a complete listing of the parameters required 
for each task. ulparmLen contains the length of pparmList in bytes. 
A NULL value for pparmList tells OS/2 that there is no parameter 
list defined for this call. OS/2 automatically ignores the ulparmLen 
parameter. 


DOsphysicalDisk data values 


Data 


Function length 
12 
22 
30 


Description 


Total number of partitionable disks in system. 


Handle for the specified partitionable disk. You can use 
this handle with Category 9 IOctl functions. 


Always set the pointer to zero. 


DOsphysicalDisk parameter values 


Data 


Function length 
10 


2 Length of string 


Description 


Always set the pointer to zero. 


An ASCIIZ string that specifies the partitionable 
disk. In most cases, this parameter uses three 
bytes. You must include the following 
in±ormahion.. DiskNumber..NULLbyte. 


The handle obtained in the data parameter of 
function 2. 


DOscancell]ockRequest 


The DOscancelLockRequest function cancels the lock range request 
of an outstanding DOssetFileLocks request. It cancels every request 
for that file. If two threads have waiting requests for a lock file range, 
then this function cancels both of them. This function uses the 
following calling syntax: 


rc = DOscancelLockRequest (hFileHandle, pLockRange) 


Not all file-system drivers (FSDs) can cancel an outstanding lock 
request. This includes LANS that use a version of OS/2 prior to 
OS/2 version 2.00. It does not include the FAT or HPFS file 
systems. 


The function provides only one return value. rc contains a return 
code that tells you whether the function completed without error. It 
also contains an error code if it didn't. Table 6-4 provides a list of 
these error codes. 


DOscancelLockRequest function return codes 


Error 


number Description 


0 NO ERROR 


6 ERROR INVALID HANDLE 


87 ERROR INVALID PARAMETER 


173 ERROR CANCEL VIOLATION 


This function uses two parameters. hFileHandle contains the file 
handle that you obtained using the DOssetFileLocks function. 
pLockBange contains the address of a structure containing the 
following information: ulFileoffset (LONG) an offset to the beginning 
of the lock range and ulBangeLength (LONG) length of the range in 
bytes. 


DOsclose 


The DOsclose function closes a file, pipe, or device handle. You 
must issue a separate call for each handle that you create using the 
DOSDupHandle function before OS/2 updates the directory and 
writes information from the internal buffers to disk. OS/2 normally 
notifies the affected device before closing the handle. When you close 
all the handles on one end of a pipe, OS/2 considers the pipe 
broken. Closing the client end of a pipe disabled it until you call 
DOSDisconnectNpipe. Closing the server end of a pipe after you 
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close the client end automatically deallocates the pipe. This function 
uses the following calling syntax: 


rc = DOsclose (hFileHandle) 


The function provides only one return value. rc contains a return 
code that tells you whether the function completed without error. It 
also contains an error code if it didn't. Table 6-5 provides a list of 
these error codes. 


DOsclose function return codes 


Error 


number Description 


0 NO ERROR 


2 ERROR FILE NOT FOUND 


5 ERROR ACCESS DENIED 


6 ERROR INVALID HANDLE 


This function uses one parameter. hFileHandle contains the file 
handle that you obtained using the DOscreateNpipe, 
DOscreatepipe, DOSDupHandle, or DOSopen functions. 


DOSCopv 


The DOSCopy function copies the source file or directory to the 
specified destination. You cannot use wildcard characters in either the 
source or destination names. The source and destination can appear 
on different drives. You cannot replace a read-only file on the 
destination path using this function (this always results in an error). If 
you use a device name as a destination, then the source name must 
contain a file, not a directory. 


The DOSCopy function does not always copy extended attributes 
(EAs) from the source to the destination. For example, it does not 
copy EAs if you want to append to an existing file. If the destination 
does not support EAs, then this function ends in an error. The 


DOSCopy function takes the following actions when an I/0 error 
occurs: 


> If the source name is a directory, it deletes the file that it was 


in the process of copying from the target path. 


> If the source name is a replacement file, it deletes the file from 


the target path. 


> If the source name is a file that you want to append, it resizes 


the target file to its original size. 


This function uses the following calling syntax: 


rc = DOSCopy (pszSourceName, pszTargetName, ulopcode) 


The function provides only one return value. rc contains a return 
code that tells you whether the function completed without error. It 
also contains an error code if it didn't. Table 6-6 provides a list of 
these error codes. 


DOSCopy function return codes 


Error 


number Description 


0 NO ERROR 


2 ERROR FILE NOT FOUND 


3 ERROR PATH NOT FOUND 


5 ERROR ACCESS DENIED 


26 ERROR NOT DOS DISK 


32 ERROR SHARING VIOLATION 


36 ERROR SHARING BUFFER EXCEEDED 


87 ERROR INVALID PARAMETER 


108 ERROR DRIVE LOCKED 


112 ERROR DISK FULL 


206 ERROR FILENAME EXCED RANGE 


267 ERROR DIRECTORY 


282 ERROR EAS NOT SUPPORTED 


283 ERROR NEED EAS NOT FOUND 


This function uses three parameters. pszSourceName contains the 
ASCIIZ name of the source file, subdirectory, or charaicter devices. 
pszTargetName contains the ASCIIZ name of destination file, 
subdirectory, or character device. ulopMode contains a DWORD 
bitmap that defines how OS/2 executes the DOSCopy function. Table 
6-7 contains a complete description of these functions. 


DOSCopy function return codes 


Bit Description 


0 Existing file disposition: 


0 = Do not copy the source file if the name already exists on the destination. OS/2 
returns an error for a single file copy when this condition exists. 
1 = Copy the source file to the destination even if the filename already exists 
(DCPY_EXISTING). 


1 Append the source file at the end of the destination file. 


0 = Replace the destination file with the source file. 
1 = Append the source file to the end of the destination file (DCPY_APPEND). 


2 Discard the EAs if the source file contains EAs and the destination does not support 


them. 
0 = Discard the EAs. 
1 = Generate an error if the file system does not support EAs (DCPY_FAILEAS). 


3-31 Reserved, alwayssetto o. 


DOscreateDir 


The DOscreateDir function creates a directory with the set of EAs 
specified by the application. If the path name contains nonexistent 
directories, then OS/2 does not create the desired subdirectory. Use the 
DOSQuerysyslnfo maximum path length supported by the operating 
system. You cannot use blanks when creating a directory on a FAT file 
system drive. This function uses the following calling syntax: 


rc = DOscreateDir (pszDirNalne, pEABuf ) 


The function provides only one return value. rc contains a return 
code that tells you whether the function completed without error. It 
also contains an error code if it didn't. Table 6-8 provides a list of 
these error codes. 


DOscreateDir function return codes Table 6-8 


Error 


numberL Description 


0 NO ERROR 


3 ERROR PATH NOT FOUND 


5 ERROR ACCESS DENIED 


26 ERROR NOT DOS DISK 


87 ERROR INVALID PARAMETER 


108 ERROR DRIVE LOCKED 


206 ERROR FILENAME EXCED RANGE 


254 ERROR INVALID EA NAME 


255 ERROR EA LIST INCONSISTENT 


1 Some texts include the ERROR EA VALUE UNSUPPORTABLE 
message. There is no standard-erro-r number associated with this 
message. 


This function uses two parameters. pszpathName contains the 
ASCIIZ name of the directory that you want to create. You must not 
specify a path longer than the path supported by the operating 
system. pEABuf contains a pointer to the EA buffer (uses the EAOP2 
data structure). If you specify a 0 value for pEABuf, then OS/2 
creates a directory without extended attributes. 


DOSDelete 


The DOS delete function removes a filename from a directory. In 
most cases, you can recover the deleted file. You cannot use wildcard 
characters with this function. OS/2 will not allow you to delete read- 
only or shared files. Use the DOssetFilelnfo function to change the 
attribute of a read-only file before calling this function. The 
DOSDeleteDir function allows you to remove directories from the 
drive. This function uses the following calling syntax: 


rc = DOSDelete (pszFileName) 


Table 6-9 


The function provides only one return value. rc contains a return 
code that tells you whether the function completed without error. It 
also contains an error code if it didn't. Table 6-9 provides a list of 
these error codes. 


DOSDelete function return codes 


Error 


number Description 


0 NO ERROR 


2 ERROR FILE NOT FOUND 


3 ERROR PATH NOT FOUND 


5 ERROR ACCESS DENIED 


26 ERROR NOT DOS DISK 


32 ERROR SHARING VIOLATION 


36 ERROR SHARING BUFFER EXCEEDED 


87 ERROR INVALID PARAMETER 


206 ERROR FILENAME EXCED RANGE 


This function uses one parameter. pszFileName contains the ASCIIZ 
name of the file that you want to delete. 


DOSDeleteDir 


The DOSDeleteDir function removes a directory from the disk drive. 
This function works only on empty directories (this includes hidden 
files). Use DOSDelete to remove the files from a directory. This 
function uses the following calling syntax: 


rc = DOSDeleteDir (pszDirName) 


The function provides only one return value. rc contains a return 
code that tells you whether the function completed without error. It 
also contains an error code if it didn't. Table 6-10 provides a list of 
these error codes. 


DOSDeleteDir Function Return Codes 
Table 6-10 


Error 


number Description 


0 NO ERROR 


2 ERROR FILE NOT FOUND 


3 ERROR PATH NOT FOUND 


5 ERROR ACCESS DENIED 


16 ERROR CURRENT DIRECTORY 


26 ERROR NOT DOS DISK 


87 ERROR INVALID PARAMETER 


108 ERROR DRIVE LOCRED 


206 ERROR FILENAME EXCED RANGE 


This function uses one parameter. pszDirName contains the ASCIIZ 
name of the directory that you want to delete. 


DOSDupHandle 


The DOSDupHandle function duplicates the handle of an open file. 
The new handle is tied to the old handle. For example, if you move 
the file pointer using one file handle, the pointer of the other 
handle moves with it. Issuing DOsclose for a handle does not 
close any of the duplicate handles. This function uses the following 
calling syntax: 


rc = DOSDupHandle (holdFileHandle, ppshfNewFileHandle) 


The function provides only one return value. rc contains a return 
code that tells you whether the function completed without error. It 
also contains an error code if it didn't. Table 6-11 provides a list of 
these error codes. 


Table 6-11 
DOSDupHandle function return codes 


Error 
number Description 


0 NO ERROR 


4 ERROR TOO MANY OPEN FILES 


6 ERROR INVALID HANDLE 


114 ERROR INVALID TARGET HANDLE 


This function uses two parameters. holdFileHandle contains the 
handle that you want to duplicate. ppshfNewFileHandle contains a 
pointer to a DWORD that contains a description of how you want to 
duplicate the handle on input, and the new file handle on output. If 
ppshfNewFileHandle contains OxFFFFFFFF on input, then OS/2 
allocates a new handle and returns it. Using any other value assigns 
that handle number to the new handle. You can specify standard 
input (OxOOOOOOOO), standard output (OxOOOOOOO1), and standard 
error (OxOOO00002) as the value for the new handle. 


DOSEditName 


The DOSEditName changes the name of files and directories by 
transforming one ASCII string into another using wildcard filename 
characters for editing or search operations on the string. You 
normally use this function with functions like DOSMove and 
DOSCopy that do not allow the use of wildcard characters. This 
function works like any DOS wildcard filename function. If you 
specify the wildcard filename in the source string, then DOSEditName 
performs a search function. If you specify the wildcard filename in the 
edit string, then DOSEditName performs an edit function. This 
function uses the following calling syntax: 


rc = DOSEditName (ulEditLevel, pszSourcestring, pszEditstring, 


pbTargetBuf , ulTargetBufLen) 


The function provides only one return value (it does provide some 
return parameters discussed in the following paragraphs). rc contains 
a return code that tells you whether the function completed without 


error. It also contains an error code if it didn't. Table 6-12 provides a 
list of these error codes. 


DOSEditName function return codes 
Table 6-12 


Error 


number Description 


0 NO ERROR 


87 ERROR INVALID PARAMETER 


123 ERROR INVALID NAME 


This function uses five parameters. usEditLevel contains the level 
of editing semantics to use in transforming the source string. A 
level of 1 uses the editing semantics of OS/2 version 1.2. 
pszSourcestring contains the ASCIIZ string that you want to 
transform. pszEditstring contains the ASCIIZ string that you want 
to use for editing. You can use wildcard characters in either 
pszSourcestring or pszEditstring. pbTargetBuf contains the 
output buffer for the resulting ASCIIZ string. ulTargetBufLen 
contains the length of pbTargetBuf in bytes. 


DOSEnumAttrib 


The DOSEnumAttrib function lists the EAs for a file or subdirectory. 
This includes the attribute name and length. You can use the 
structure that this function returns in PEnumBuf to calculate the 
buffer length required to store the entire EA structure returned by the 
DOSQuerypathlnfo or DOSQueryFilelnfo functions. Each field in the 
pEnumBuf structure contributes toward the overall length of the full 
EA (FEA) buffer. Each EA entry starts on a DWORD boundary. Table 
6-13 provides the information that you need to calculate the buffer 
length. Simply add the entries together to obtain the overall length of 
the buffer. You could simplify this equation to 9 bytes + value of 
cbName + value of cbvalue. 


Table 6-13 


-_ _ --_ : - 


FEA buffer length entities 


Size D es cription 


4 oNextEntryoffset-Number of bytes to the beginning of the next EA 


data structure. Remember that each structure begins on a DWORD 
boundary. A value of 0 in this field indicates that this is the last data 
structure. 


1fEA 


1 cbName 


2 cbvalue 


Value of EA name 
cbName 


1 Terminating NULL in cbName 


Value of EA value 
cbvalue 


OS/2 allows you to cycle through the EA entries. To obtain the next 
EA entry, simply set the ulEntryNum value to its previous value plus 
the value of pEntrycnt. The DOSEnumAttribute function does not 
control EA ordering; it merely lists them for you. 


You also need to consider the multitasking nature of OS/2 when 
enumerating the EAs. The value returned for EA 11 on one call might 
contain a different value on a second call. A DOssetFilelnfo or 
DOssetpathlnfo call could modify the entry during or after the time 
that you read it. Open the file using the deny-write attribute to 
prevent this from happening. Of course, this could result in a sharing 
violation should another process need to open the file. You do not 
need to worry about this when checking the EAs of a directory entry 
because two processes cannot share it. This function uses the 
following calling syntax: 


rc = DOSEnumAttribute (ulRefType, pFileRef , ulEntryNum, pEnumBuf , 


ulEnumBufsize, pEnulncnt, ullnfoLevel) 


The function provides only one return value (it does provide some 
return parameters discussed in the following paragraphs). rc contains 
a return code that tells you whether the function completed without 
error. It also contains an error code if it didn't. Table 6-14 provides a 
list of these error codes. 


DOSEnumAttribute function return codes 
Table 6-14 


Error 
number Description 


0 NO ERROR 


3 ERROR PATH NOT FOUND 


5 ERROR ACCESS DENIED 


6 ERROR INVALID HANDLE 


8 ERROR INVALID PARAMETER 


87 ERROR INVALID PARAMETER 


111 ERROR BUFFER OVERFLOW 


124 ERROR INVALID LEVEL 


206 ERROR FILENAME EXCED RANGE 


This function uses seven parameters. ulBefType indicates whether 
pFileBef points to a handle or an ASCIIZ name. A value of 0 
indicates a file handle, while a value of 1 indicates a file or 
subdirectory. pFileBef contains a pointer to the file handle or the 
ASCIIZ name of a file or subdirectory. ulEntryName contains the 
ordinal number of the EA entry that you want to retrieve. Never use a 
value of 0; 1 indicates the first EA entry. pEnumBuf contains a 
pointer to the buffer used to store the EA information. This entry 
uses a data structure of type DENA2. ulEnumBufsize contains the 
length of pEnumBuf (normally 9 bytes). pEnumBuf contains the 
number of EAs that you want returned on entry. Using a value of -1 
returns all the EAs that pEnumBuf can hold. This parameter contains 
the actual number of EAs returned on exit. ullnfoLevel contains the 
level of information that you require. The only valid entry is 
ENUMEA LEVEL_NO_VALUE (1), which indicates you require level 
1 information. 


DOSFindclose 


The DOSFindclose function closes a find request handle, ending the 
current search. You cannot issue a DOSFindNext call after using this 


Table 6-15 


function unless you issue a DOSFindFirst call first. This function uses 
the following calling syntax: 


rc = DOSFindclose (hdirDirHandle) 


The function provides only one return value. rc contains a return 
code that tells you whether the function completed without error. It 
also contains an error code if it didn't. Table 6-15 provides a list of 
these error codes. 


DOscloseFind function return codes 


Error 
number Description 


0 NO ERROR 


6 ERROR INVALID HANDLE 


This function uses one parameter. hdirDirHandle contains the 
directory handle that you obtained using the DOSFindFirst function. 
This is the same handle you used to perform a directory search with 
the DOSFindNext function. 


DOSFindFirst 


The DOSFindFirst function finds the first of one or more file objects 
that match the file specification you supply. The file specification can 
include wildcard characters. This function returns the specified 
number of directory entries (if possible) and their matching EA 
information. You use the DOSFindNext function to continue the 
process of finding and returning directory entries. This function uses 
the following calling syntax: 


rc = DOSFindFirst (pszFileNalne, pphdirDirHandle, ulAttribute, 


pResultBuf , ulResultBufLen, psearchcount, ulFilelnfoLevel) 


The function provides only one return value (it does provide some 
return parameters discussed in the following paragraphs). rc contains 
a return code that tells you whether the function completed without 
error. It also contains an error code if it didn't. Table 6-16 provides a 
list of these error codes. 


DOSFindFirst function return codes 
Table 6-16 


Error 
number Description 


0 NO ERROR 


2 ERROR FILE NOT FOUND 


3 ERROR PATH NOT FOUND 


6 ERROR INVALID HANDLE 


18 ERROR NO MORE FILES 


26 ERROR NOT DOS DISK 


87 ERROR INVALID PARAMETER 


108 ERROR DRIVE LOCKED 


111 ERROR BUFFER OVERFLOW 


113 ERRO NO MORE SEARCH HANDLES 


206 ERROR FILENAME EXCED RANGE 


208 ERROR META EXPANSION TOO LONG 


254 ERROR INVALID EA NAME 


255 ERROR EA LIST INCONSISTENT 


275 ERROR EAS DIDN'T FIT 


This function uses seven parameters. pszFileName contains the 
ASCIIZ filename or subdirectory that you want to find. You can use 
wildcard characters with this parameter. pphdirDirHandle contains 
the handle associated with the DOSFindFirst request. You can supply 
the following values for this parameter: OxOOOOOOOO (assign the 
standard output handle) or OxFFFFFFFF (allocate and return a search 
handle). ulAttribute contains the file attribute values that you want to 
find. These attribute bits include: FILE_READONLY (0), 
FILE_HIDDEN (1), FILE_SYSTEM (2), reserved (3), 
FILE_DIRECTORY (4), FILE_ARCHIVED (5), reserved (6 and 7), 
MUST_HAVE_READONLY (8), MUST_HAVE_HIDDEN (9), 
MUST_HAVE_SYSTEM (10), reserved (11), 
MUST_HAVE_DIRECTORY (12), MUST_HAVE_ARCHIVED (13), 
and reserved (14 through 31). You can use these bits individually or 
in combination. The only attribute that you cannot specify is the 
volume label attribute. Use the DOSQueryFslnfo function to obtain 


this information. On entry, pBesultBuf contains a pointer to the 
directory search structures for file object information levels 1 through 
3. Use the value of ulFilelnfoLevel to determine which search 
structure to use. The information returned in the buffer reflects the 
most recent call to DOsclose or DOSResetBuffer. ulBesultBufLen 
contains the length of pBesultBuf in bytes. psearchcount contains 
the number of matching entries that you want on entry. On exit, this 
parameter contains the number of entries placed in ppesultBuf . 
ulFilelnfoLevel contains the level of information that you require. 
These levels include: FIL_STANDARD (level 1), FIL_QUERYEASIZE 
(level 2), and FIL_QUERYEASFROMLIST (level 3). 


Table 6-17 


DOSFindNext 


The DOSFindNext function performs subsequent searches for file or 
directory names using the handle obtained using the DOSFindFirst 
function. This function uses the following calling syntax: 


rc = DOSFindNext (hdirDirHandle, pResultBuf , ulResultBufLen, 


psearchcount ) 


The function provides only one return value (it does provide some 
return parameters discussed in the following paragraphs). rc contains 
a return code that tells you whether the function completed without 
error. It also contains an error code if it didn't. Table 6-17 provides a 
list of these error codes. 


DOSFindNext function return codes 


Error 


number Description 


0 NO ERROR 


6 ERROR INVALID HANDLE 


18 ERROR NO MORE FILES 


26 ERROR NOT DOS DISK 


87 ERROR INVALID PARAMETER 


111 ERROR BUFFER OVERFLOW 


275 ERROR EAS DIDN'T FIT 


This function uses four parameters. hdirDirHandle contains the 
directory handle. On entry, pBesultBuf contains a pointer to the 
directory search structures for file object information levels 1 through 
3. The information returned in the buffer reflects the most recent 
call to DOsclose or DOSResetBuffer. You normally use the same 
structure used for the DOSFindFirst call. ulBesultBufLen contains the 
length of pBesultBuf in bytes. psearchcount contains the number of 
matching entries you want on entry. On exit, this parameter contains 
the number of entries placed in pBesultBuf. 


DOSForceDelete 


The DOSForceDelete function permanently removes a filename from 
a directory. You cannot recover the file. OS/2 does not allow you 
to use wildcard characters with this function. In addition, this 
function will not delete read-only files or subdirectories. Use the 
DOssetFilelnfo function to change the attribute of read-only files. 
The DOSDeleteDir function allows you to delete directories. This 
function uses the following calling syntax: 


rc = DOSForceDelete (pszFileName) 


The function provides only one return value. rc contains a return 
code that tells you whether the function completed without error. It 
also contains an error code if it didn't. Table 6-18 provides a list of 
these error codes. 


DOSForceDelete function return codes 
Table 6-1 8 


Error 


number Description 


0 NO ERROR 


2 ERROR FILE NOT FOUND 


3 ERROR PATH NOT FOUND 


5 ERROR ACCESS DENIED 


26 ERROR NOT DOS DISK 


32 ERROR SHARING VIOLATION 


Table 6-18 Continued 


Table 6-19 


Error 


number Description 


36 ERROR SHARING BUFFER EXCEEDED 


87 ERROR INVALID PARAMETER 


206 ERROR FILENAME EXCED RANGE 


This function uses one parameter. pszFileName contains the name of 
the file you want to delete. 


DOSFSAttach 


The DOSFSAttach function attaches or detaches a drive to or from a 
remote file system driver (FSD). You also can use it to attach or 
detach a pseudocharacter device name to or from a local or remote 
FSD. This function does not support the redirection of local drives. 
This function uses the following calling syntax: 


rc = DOSFSAttach (pszDeviceNalne, pszFSDName, pDataBuffer, 


ulDataBuf ferLen, ulopFlag) 


The function provides only one return value (it does provide some 
return parameters discussed in the following paragraphs). rc contains 
a return code that tells you whether the function completed without 
error. It also contains an error code if it didn't. Table 6-19 provides a 
list of these error codes. 


DOSFSAttach function return codes 


Error 


number Description 


NO ERROR 
ERROR NOT ENOUGH MEMORY 


ERROR INVALID DRIVE 


ERROR INVALID LEVEL 


ERROR INVALID FSD NAME 


ERROR INVALID PATH 


This function uses five parameters. pszDeviceName contains the 
drive designation or a pseudocharacter device name when 
ulopFlag equals 0 or 1. This parameter contains the name of a 
spooled device when ulopFlag equals 2 or 3. A drive designation 
or spooled device name is an ASCIIZ string containing a drive 
letter and a colon. The file system does not see requests to a 
spooled device. A pseudocharacter device name consists of an 
ASCIIZ string with the filename subdirectory "\DEV\ ". The file 
system receives all requests for the pseudocharacter device name 
after successful attachment. pszFSDName contains the ASCIIZ 
name of the remote file system. Set this parameter to 0 when 
ulopFlag equals 2 or 3. pDataBuffer contains a pointer to the 
user supplied FSD argument data area when ulopFlag equals 0 or 
1. The format of this data varies from driver to driver. The 
parameter contains the following information when ulopFlag 
equals 2: hNmpipe (WORD), cbspoolobj (BYTE), and 
szSpoolobj (ASCIIZ). Always set pDataBuffer to 0 when 
ulopFlag equals 3. ulDataBufferLen contains the length of 
pDataBuffer in bytes. ulopFlag determines which operation this 
function performs: attach (0), detach (1), spool attach (2), or spool 
detach (3). 


DOSFSctl 


The DOSFSctl function provides an extended standard interface 
between an application and an FSD. This function uses the following 
calling syntax: 


rc = DOSFSctl (pDataArea, ulDataLengthMax, pDataLengthlnout, 


pparmList, ulparmLengthMax, pparmLengthlnout , 
ulFunctioncode, pszRouteName, hFileHandle, ulRouteMethod) 


The function provides only one return value (it does provide some 
return parameters discussed in the following paragraphs). rc contains 
a return code that tells you whether the function completed without 
error. It also contains an error code if it didn't. Table 6-20 provides a 
list of these error codes. 


Table 6-20 DOSFSctl function return codes 


Error 


number Description 


0 NO ERROR 


1 ERROR INVALID FUNCTION 


6 ERROR INVALID HANDLE 


87 ERROR INVALID PARAMETER 


95 ERROR INTERRUPT 


111 ERROR BUFFER OVERFLOW 


117 ERROR INVALID CATEGORY 


124 ERROR INVALID LEVEL 


252 ERROR INVALID FSD NAME 


This function uses ten parameters. pDataArea contains the data area 
address. ulDataLengthMax contains the length of pDataArea in bytes 
(the maximum length of the data returned by the FSD). 
pDataLengthlnout can contain a larger value than ulDataLengthMax 
on input, but not on output. pDataLengthlnout contains the length of 
the data passed to the FSD on input. It contains the length of the data 
passed by the FSD in pDataArea on output. If the function returns with 
an ERROR_BUFFER_OVERFLOW error, then this parameter contains 
the buffer length required to hold the FSD data. pparmList contains a 
command-specific parameter list. ulparmLengthMax contains the length 
of pparmList in bytes (the maximum data length that the FSD can 
return). pparmLength contains the length of the data sent to the FSD 
on input. It contains the length of the data returned by the FSD on 
output. If the function returns an ERROR_BUFFER_OVERFLOW error, 
then this parameter holds the buffer size required to hold the FSD data. 
ulFunctioncode contains an FSD specific function code. 
pszBouteName contains the ASCIIZ name of the FSD or the path 
name of a file or directory. hFileHandle contains a file or device specific 
handle. ulBouteMethod selects the request routing method: 
FSCTL_HANDLE (1) file handle directs routing and the FSD associated 
with the file handle receives the request, FSCTL_PATHNAME (2) path 
name directs routing and the FSD associated with the drive associated 
with the path name receives the request, and FSCTL_FSDNAME (3) 
FSD name directs routing. 


DOSMove 


The DOSMove function moves a file from one location to another on 
the same drive. It does not provide for inter-drive transfers. You also 
can use this function to change the filename. The DOSMove function 
does not allow you to use wildcard characters. There are other 
limitations that you need to observe when using this function: 


> Attempts to move a parent directory to a position below one of 


its children always fails. 


> Attributes always travel with the file to its new location. 


> You cannot replace read-only files in the target directory. 


> Always use the DOSQuerysyslnfo function to determine the 


maximum path length allowed by the operating system. 


You can use the DOSMove function to change the case of a file on a 
drive controlled by an FSD. This function uses the following calling 
syntax: 


rc = DOSMove (pszoldpathName, pszNewpathName) 


The function provides only one return value. rc contains a return 
code that tells you whether the function completed without error. It 
also contains an error code if it didn't. Table 6-21 provides a list of 
these error codes. 


DOSMove function return codes 
Table 6-21 


Error 
number Description 


0 NO ERROR 


2 ERROR FILE NOT FOUND 


3 ERROR PATH NOT FOUND 


5 ERROR ACCESS DENIED 


17 ERROR NOT SAME DEVICE 


26 ERROR NOT DOS DISK 


Table 6-21 Continued 


Error 
number Description 


32 ERROR SHARING VIOLATION 


36 ERROR SHARING BUFFER EXCEEDED 


87 ERROR INVALID PARAMETER 


108 ERROR DRIVE LOCKED 


206 ERROR FILENAME EXCED RANGE 


2 5 0 ERRO R_CIRCUIARITY_REQ UESTED 


251 ERROR DIRECTORY IN CDS 


This function uses two parameters. pszoldpathName contains the 
name of the file or subdirectory that you want to move and/or 
rename. pszNewpathName contains the new file or subdirectory 
name (including the new path information). 


DOSopen 


The DOSopen function opens a new file, an existing file, or a 
replacement for an exiting file. It returns a handle that you can use to 
access the file and sets the read/write pointer to the first byte in the 
file. Use the DOssetFileptr function to change the position of the file 
pointer. You can provide EAs for an open file. This function uses the 
following calling syntax: 


rc = DOSopen (pszFileName, ppshfFileHandle, pActionTaken, 


ulFilesize, ulFileAttribute, ulopenFlag, ulopenMode, pEABuf ) 


The function provides only one return value (it does provide some 
return parameters discussed in the following paragraphs). rc contains 
a return code that tells you whether the function completed without 
error. It also contains an error code if it didn't. Table 6-22 provides a 
list of these error codes. 
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DOS0pen function return codes 
Table 6-22 


Error 
number Description 


0 NO ERROR 


2 ERROR FILE NOT FOUND 


3 ERROR PATH NOT FOUND 


4 ERROR TOO MANY OPEN FILES 


5 ERROR ACCESS DENIED 


12 ERROR INVALID ACCESS 


26 ERROR NOT DOS DISK 


32 ERROR SHARING VIOIAIION 


36 ERROR SHARING BUFFER EXCEEDED 


82 ERROR CANNOT MAKE 


87 ERROR INVALID PARAMETER 


99 ERROR DEVICE IN USE 


108 ERROR DRIVE LOCKED 


110 ERROR OPEN FAILED 


112 ERROR DISK FULL 


206 ERROR FILENAME EXCED RANGE 


231 ERROR PIPE BUSY 


This function uses eight parameters. pszFileName contains the name 
of the file or device you want to open. ppshfFileHandle contains the 
file handle on exit. pEABuf contains the EA buffer which uses the 
EAOP2 structure. If you set this parameter to zero, the DOSopen 
does not define any EAs for the file. 


pActionTaken contains a value to define the action taken by the 
DOSopen function that includes: FILE_EXISTED (1), 
FILE_CREATED (2), or FILE_TRUNCATED (3). This value has no 
meaning if the open fails. ulFilesize contains the new logical file size 
in bytes. The function ignores this parameter unless you create a new 
file or replace an existing one. You cannot create or replace a file 
with a zero length if the ulopenMode parameter contains the read- 
only flag. 


ulFileAttribute contains the file attribute bits: FILE NORMAL or 
FILE_READONLY (0), FILE_HIDDEN (1), FILE_SY-STEM (2), reserved 
(3), FILE_DIRECTORY (4), FILE_ARCHIVED (5), and reserved (6 
through 31). The function ignores this parameter unless you create a 
new file. You can use these bits individually or in combination. 


ulopenFlag contains flags that determine the action that DOSopen 
takes depending on whether the file exists or not. The values for bits 0 
through 3 include: OPEN_ACTION_REPLACE_IF_EXISTS, 
OPEN_ACTION_OPEN_IF_EXISTS , and 
OPEN_ACTION_FAIL_IF_EXITS. The values for bits 4 though 7 
include: OPEN ACTION CREATE IF NEW and 
OPEN_ACTION_FAIL_IF-_NEW. You must set bits 8 through 31 to zero. 


ulopenMode defines the open function mode. Bits 0 through 2 
contain the access mode flags: OPEN_ACCESS_READONLY, 
OPEN_ACCESS_WRITEONLY, or OPEN_ACCESS_READWRITE. Bit 
3 is reserved; always set it to zero. Bits 4 through 6 contain the share 
access mode. flags: OPEN_SHARE DENYREADWRITE, 
OPEN_SHARE_DENYWRITE, OPEN_SHARE_DENYREAD, or 
OPEN_SHARE_DENYNONE. Bit 7 contains the inheritance flag: a 
process created by DOSExecprg inherits the flag (0) or flag private to 
the current process (1). Bits 8 through 10 contain the locality of 
reference flags: OPEN_FLAGS_NO_LOCALITY, 
OPEN_FLAGS_SEQUENTIAL, OPEN_FLAGS_RANDOM, or 
OPEN_FLAGS_RANDOMSEQUENTIAL. Bit 11 is reserved; set it to 
zero. Bit 12 contains the cache/no-cache flag (cache when set to 0). 
Bit 13 contains the fail errors flag: report through the system critical- 
error handler (0) or report directly to the caller (1). Bit 14 contains 
the write-through flag (write-through mode when set to 1). Bit 15 
contains the direct open flag: open normally (0) or mounted volume 
to open for direct access (1). Bits 16 through 31 are reserved; set 
them to 0. 


DOSQuervcurrentDir 


The DOSQuerycurrentDir function returns the full path name of the 
current directory for the specified drive. Neither the drive letter nor 


an initial backslash (\) appear as part of the returned string. This 
function uses the following calling syntax: 


rc = DOSQuerycurrentDir (ulDriveNumber, pbDirpath, pDirpathLen) 


The function provides only one return value (it does provide some 
return parameters discussed in the following paragraphs). rc contains 
a return code that tells you whether the function completed without 
error. It also contains an error code if it didn't. Table 6-23 provides a 
list of these error codes. 


DOSQuerycurrentDir function return codes 
Table 6-23 


Error 
number Description 


0 NO ERROR 


15 ERROR INVALID DRIVE 


26 ERROR NOT DOS DISK 


108 ERROR DRIVE LOCKED 


111 ERROR BUFFER OVERFLOW 


This function uses three parameters. ulDriveNumber contains the 
drive number. Use a value of 0 for the current drive or a 1-based 
number for a specific drive. pbDirpath contains the fully qualified 
path name of the current directory. pDirpathLen contains the length 
of pbDirpath in bytes on input. If an error occurs, this parameter 
contains the buffer length required to hold the path information. 


DOSQuervcurrentDisk 


The DOSQuerycurrentDisk function returns the current default drive for 
the requesting process. This function uses the following calling syntax: 


rc = DOSQuerycurrentDrive (pDriveNumber, pLogicalDriveMap) 


The function provides only one return value (it does provide some 
return parameters discussed in the following paragraphs). rc contains 


a return code that tells you the function completed without error 
(NO_ERROR). There are no error codes associated with this function. 


This function uses two parameters. pDriveNumber contains the 1- 
based number of the default drive. For example, drive A equals 1. 
pLogicalDriveMap contains a bitmap where the system returns 
the logical drive map as a DWORD. This is a zero-based 
representation, with each drive consuming one bit (bits 26 through 
31 always contain 0). A value of 1 in a specific drive location 
indicates that logical drive exists. 


DOSQuervFHstate 


The DOSQueryFHstate function returns the state of the specified file 
handle. You can use this function to return critical error handling 
control to the system when the application cannot handle it by 
turning off the fail/error bit and reissuing the failed I/0 call. The 
Direct I/0 flag provides physical access to the drive by bypassing the 
FSD. This function uses the following calling syntax: 


rc = DOSQueryFHstate (hFileHandle, pFileHandlestate) 


The function provides only one return value (it does provide some 
return parameters discussed in the following paragraphs). rc contains 
a return code that tells you whether the function completed without 
error. It also contains an error code if it didn't. Table 6-24 provides a 
list of these error codes. 


DOSQueryFHstate Function Return Codes 


Error 
number Description 


0 NO ERROR 


6 ERROR INVALID HANDLE 


87 ERROR INVALID PARAMETER 


This function uses two parameters. hFileHandle contains the file 
handle you want to query. pFileHandlestate defines the file handle 
status. Bits 0 through 2 contain the access mode flags: 
OPEN_ACCESS_READONLY, OPEN_ACCESS_WRITEONLY, or 
OPEN_ACCESS_READWRITE. Bit 3 is reserved. Bits 4 through 6 
contains the share access mode flags: 
OPEN_SHARE_DENYREADWRITE, OPEN_SHARE_DENYWRITE, 
OPEN_SHARE_DENYREAD, or OPEN_SHARE_DENYNONE. Bit 
7 contains the inheritance flag: a process created by DOSExecprg 
inherits the flag (0) or flag private to the current process (1). Bits 
8 through 11 are reserved; set it to zero. Bit 12 contains the 
cache/no-cache flag (cache when set to 0). Bit 13 contains the fail 
errors flag: report through the system critical-error handler (0) or 
report directly to the caller (1). Bit 14 contains the write-through 
flag (write-through mode when set to 1). Bit 15 contains the direct 
open flag: open normally (0) or mounted volume to open for direct 
access (1). 


DOSQuervFile[nfo 


The DOSQueryFilelnfo function returns information about the 
specified file. It returns only the date and time information when 
requesting level 1 file information on a FAT drive. You must open the 
file with read access and a deny-write sharing mode using the 
DOSopen function before calling this function to obtain information 
at the file information level. This function uses the following calling 
syntax: 


rc = DOSQueryFilelnfo (hFileHandle, ulFilelnfoLevel, 


pFilelnfoBuf , ulFilelnfoBufsize) 


The function provides only one return value (it does provide some 
return parameters discussed in the following paragraphs). rc contains 
a return code that tells you whether the function completed without 
error. It also contains an error code if it didn't. Table 6-25 provides a 
list of these error codes. 


Table 6-25 DOSQueryFHstate Function Return codes 


Error 


number Description 


0 NO ERROR 


5 ERROR ACCESS DENIED 


6 ERROR INVALID HANDLE 


111 ERROR BUFFER OVERFLOW 


124 ERROR INVALID LEVEL 


130 ERROR DIRECT ACCESS HANDLE 


254 ERROR INVALID EA NAME 


255 ERROR EA LIST INCONSISTENT 


This function uses four parameters. hFileHandle contains the file 
handle. ulFilelnfoLevel contains the level of file information you want 
returned: FIL_STANDARD (level 1), FIL_QUERYEASIZE (level 2), or 
FIL_QUERYEASFROMLIST (level 3). pFilelnfoBuf contains the 
address of the storage area for the file information. Each level of 
returned file information uses a different buffer: FILESTATUS3 (level 
1), FILESTATUS4 (level 2), and EAOP2 (level 3). pFilelnfoBufsize 
contains the length of pFilelnfoBuf in bytes. 


DOSQuervFSAttach 


The DOSQueryFSAttach returns information about the attached file 
system. You also can use it to retrieve information about a character 
or pseudocharacter device attached to the file system. This function 
retrieves information about all block, character, and pseudocharacter 
devices. Because the subject of the information you request changes 
frequently, you might receive invalid information. There are two ways 
to use the information that you receive: to determine if the kernel 
recognizes the disk as one attached to its file system or to determine 
if the kernel attached its file system to the disk because the disk had 
no other FSDs attached. This function uses the following calling 
syntax: 


rc = DOSQueryFSAttach (pszDeviceName, ulordinal, ulFSAlnfoLevel, 


pDataBuf fer, pDataBuf ferLen) 


The function provides only one return value (it does provide some 
return parameters discussed in the following paragraphs). rc contains 
a return code that tells you whether the function completed without 
error. It also contains an error code if it didn't. Table 6-26 provides a 
list of these error codes. 


DOSQueryFSAttach function return codes 
Table 6-26 


Error 


number Description 


0 NO ERROR 


15 ERROR INVALID DRIVE 


111 ERROR BUFFER OVERFLOW 


124 ERROR INVALID LEVEL 


259 ERROR NO MORE ITEMS 


This function uses five parameters. pszDeviceName contains a drive 
designation or the name of a character or pseudocharacter device. A 
drive designation consists of an ASCIIZ string containing a drive letter 
followed by a colon. A character or pseudocharacter name consists of 
an ASCIIZ string continuing the filename and the subdirectory DEV. 
The function ignores this parameter for level 2 or 3 information 
(specified in ulFSAlnfoLevel). ulordinal contains an index into 
the list of character devices, pseudocharacter devices, or drive 
designators. Use this parameter to step through the list. The ordinal 
number to item relationship is volatile; it can change from one call 
to the next. ulFSAlnfoLevel contains the level of information 
returned in pDataBuffer: FSAIL_QUERYNAME (level 1), 
FSAIL_DEVNUMBER (level 2), or FSAIL_DRVNUMBER (level 3). 
pDataBuffer contains the returned information. This buffer contains 
the following fields: iType, cbName (which contains the item name 
length in bytes), cbFSDName (which contains the FSD name length 
in bytes), szName (which contains the ASCIIZ item name), 
szFSDName (which contains the ASCIIZ FSD name), and rgFSAData 
(which contains the FSD attach data). There are four different item 


types returned in iType: FSAT_CHARDEV (1), FSAT_PSEUDODEV 
(2), FSAT_LOCALDRV (3), or FSAT_REMOTEDRV (4). 
pDataBufferLen contains the length of pDataBuffer on entry. It 
contains the actual data length on exit. 


Table 6-27 


DOSQuervFslnfo 


The DOSQueryFslnfo function returns information from the FSD. It 
does not return trailing volume label blanks. The maximum volume 
label length is 11 bytes. The volume serial number is a unique 32-bit 
number that the operating system uses to identify the disk or diskette 
volumes. This function uses the following calling syntax: 


rc = DOSQuerycurrentDir (ulDriveNumber, ulFslnfoLevel, 


pFslnfoBuf , ulFslnfoBufsize) 


The function provides only one return value (it does provide some 
return parameters discussed in the following paragraphs). rc contains 
a return code that tells you whether the function completed without 
error. It also contains an error code if it didn't. Table 6-27 provides a 
list of these error codes. 


DOSQueryFslnfo function return codes 


Error 
number Description 


0 NO ERROR 


15 ERROR INVALID DRIVE 


111 ERROR BUFFER OVERFLOW 


124 ERROR INVALID LEVEL 


125 ERROR NO VOLUME IABEL 


This function uses four parameters. ulDriveNumber contains the 1- 
based logical drive number. Using a value of 0 returns the information 
about the current drive. The attached FSD or FSD responsible for 
managing the drive's media type returns information about the 
specified drive. ulFslnfoLevel determines the level of information 


that the function returns: FSIL_ALLOC (level 1) or FSIL_VOLSER 
(level 2). pFslnfoBuf contains the information returned by the FSD. 
It includes the following fields for level 1 information: file system ID 
(ULONG), number of sectors per allocation unit (ULONG), number of 
allocation units (ULONG), number of available allocation units 
(ULONG), and number of bytes per sector (USHORT). It includes the 
following fields for level 2 information: volume serial number 
(ULONG), length of the volume label in bytes (BYTE), and the ASCIIZ 
volume label (CHAR). ulFslnfoBufsize contains the size of 
ulFslnfoBuf in bytes. 


DOSQuervHrtype 


The DOSQueryHType function determines if a handle refers to a 
device or file. This function uses the following calling syntax: 


rc = DOSQuerycurrentDir (hFileHandle, pHandleType, pFlagword) 


The function provides only one return value (it does provide some 
return parameters discussed in the following paragraphs). rc contains 
a return code that tells you whether the function completed without 
error. It also contains an error code if it didn't. Table 6-28 provides a 
list of these error codes. 


DOSQueryHType function return codes 
Table 6-28 


Error 
number Description 


0 NO ERROR 


6 ERROR INVALID HANDLE 


This function uses three parameters. hFileHandle contains the file 
handle. pHandleType contains the handle type bits on return: handle 
type (0 through 7), reserved (8 through 14), and network bit (0 for 
local or 1 for remote) (15). The handle types include: disk file (0), 
character device (1), and pipe (2). pFlagword contains the address of 
the device driver attribute word if the handle type is a local character 
device. 


Table 6-29 


DOSQuervpathlnfo 


The DOSQuerypathlnfo function returns the file information for a file 
or subdirectory. You must open the file for read access with deny- 
write sharing mode before calling this function. This function uses the 
following calling syntax: 


rc = DOSQuerypathlnfo (pszpathName, ulpathlnfoLevel, 


ppathlnfoBuf , ulpathlnfoBufsize) 


The function provides only one return value (it does provide some 
return parameters discussed in the following paragraphs). rc contains 
a return code that tells you whether the function completed without 
error. It also contains an error code if it didn't. Table 6-29 provides a 
list of these error codes. 


DOSQuerypathlnfo function return codes 


Error 


number Description 


0 NO ERROR 


3 ERROR PATH NOT FOUND 


32 ERROR SHARING VIOLATION 


111 ERROR BUFFER OVERFLOW 


124 ERROR INVALID LEVEL 


206 ERROR FILENAME EXCED RANGE 


254 ERROR INVALID EA NAME 


255 ERROR EA LIST INCONSISTENT 


This function uses four parameters. pszpathName contains the 
ASCIIZ full path name of the file or subdirectory. You can use 
wildcard characters when requesting level 5 information. 
ulpathlnfoLevel contains the level of information you require: 
FIL_STANDARD (level 1), FIL_QUERYEASIZE (level 2), 
FIL_QUERYEASFROMLIST (level 3), reserved (level 4), and 
FIL_QUERYFULLNAME (level 5). ppathlnfoBuf contains the path 
information. Each information level uses a different structure for this 


information: FILESTATUS3 (level 1), FILESTATUS4 (level 2), EAOP2 
(level 3), or fully qualified ASCIIZ name of pszpathName. 
ulpathlnfoBufsize contains the size of ppathlnfoBuf in bytes. 


DOSQuervsvslnfo 


The DOSQuerysyslnfo function returns the values of static system 
variables. You can request a single variable by setting the start index 
equal to the last index. Each variable is a DWORD value. The values 
you can retrieve include: QSV_MAX_PATH_LENGTH, 
QSV_MAX_TEXT_SESSIONS, QSV_MAX_PM_SESSIONS , 
QSV_MAX_VDM_SESSIONS, QSV_BOOT_DRIVE, 
QSV_DYN_PRI_VARIATION , QSV_MAX_WAIT, QSV_MIN_SLICE, 
QSV_MAX_SLICE, QSV_PAGE_SIZE, QSV_VERSION_MAJOR, 
QSV_VERSION_MINOR, QSV_VERSION_REVISION, 
QSV_MS_COUNT, QSV_TIME_LOW, QSV_TIME_HIGH, 
QSV_TOTPHYSMEM, QSV_TOTRESEMEM, QSV_TOTAVAILMEM, 
QSV_MAXPRMEM, QSV_MAXSHMEM, QSV_TIMER_INTERVAL, 
and QSV_MAX_COMP_LENGTH. This function uses the following 
calling syntax: 


rc = DOSQuerycurrentDir (ulstartlndex, ulLastlndex, pDataBuf , 


ulDataBufLen) 


The function provides only one return value (it does provide some 
return parameters discussed in the following paragraphs). rc contains 
a return code that tells you whether the function completed without 
error. It also contains an error code if it didn't. Table 6-30 provides a 
list of these error codes. 


DOSQuerysyslnfo function return codes 
Table 6-30 


Error 


number Description 


0 NO ERROR 


87 ERROR INVALID PARAMETER 


111 ERROR BUFFER OVERFLOW 


This function uses four parameters. ulstartlndex contains the value of 
the first system variable to return. ulLastlndex contains the value of 
the last system variable to return. pDataBuf contains a pointer to the 
buffer where OS/2 returns the variable values. pDataBufLen contains 
the length of pDataBuf in bytes. 


DOSQuervverify 


The DOSQueryverify function returns the write verification status. Write 
verification ensures that the data written to disk matches the original 
data in memory. This function uses the following calling syntax: 


rc = DOSQueryverify (pverifysetting) 


The function provides only one return value (it does provide some 
return parameters discussed in the following paragraphs). rc contains 
a return code that tells you that the function completed without error 
(NO_ERROR). There are no error codes associated with this function. 


This function uses one parameter. pverifysetting contains a pointer 
to the current verify setting. A value of 1 indicates the write verify is 
active. 


DOSFtead 


The DOSRead function returns the specified number of bytes from a 
file, pipe, or device to a buffer. This function attempts to read the 
number of bytes requested but will not read beyond the end of file. A 
return value of 0 indicates that the read pointer is at the end of the 
file. OS/2 automatically moves the read pointer each time that you 
use this function. You also can use the DOssetFileptr function to 
move the read pointer. 


This function also allows direct reads from an entire disk or diskette 
volume when you set the direct open flag to 1. Direct access bypasses 
the FSD. Always lock the volume before you read from it and unlock 
it when you finish. This function uses the following calling syntax: 


rc = DOSRead (hFileHandle, pBufferArea, ulBufferLength, 


pBytesRead) 


The function provides only one return value (it does provide some 
return parameters discussed in the following paragraphs). rc contains 
a return code that tells you whether the function completed without 
error. It also contains an error code if it didn't. Table 6-31 provides a 
list of these error codes. 


DOSRead function return codes 
Table 6-31 


Error 
number Description 


0 NO ERROR 


5 ERROR ACCESS DENIED 


6 ERROR INVALID HANDLE 


26 ERROR NOT DOS DISK 


33 ERROR LOCK VIOLATION 


109 ERROR BROREN PIPE 


234 ERROR MORE DATA 


This function uses four parameters. hFileHandle contains the file 
handle you obtained using the DOSopen function. pBufferArea 
contains the data read from the file, device, or pipe. ulBufferLength 
contains the length of pBufferArea in bytes. pBytespead contains 
the number of bytes that the function actually returned. 


DOSResetBuffer 


The DOSResetBuffer function writes the buffers for the specified file 
to a device. Using this function on a file updates the file's directory 
entry as if you closed the file; however, the file remains open. Issuing 
this function for a pipe blocks the function at one end of the pipe 
until all the data gets written to the other end. This function uses the 
following calling syntax: 


rc = DOSResetBuffer (hFileHandle) 


Table 6-32 


The function provides only one return value (it does provide some 
return parameters discussed in the following paragraphs). rc contains 
a return code that tells you whether the function completed without 
error. It also contains an error code if it didn't. Table 6-32 provides a 
list of these error codes. 


DOSResetBuffer function return codes 


Error 


number Description 


0 NO ERROR 


2 ERROR FILE NOT FOUND 


5 ERROR ACCESS DENIED 


6 ERROR INVALID HANDLE 


This function uses one parameter. hFileHandle contains the file 
handle whose buffers you want to write to disk. A value of OxFFFF 
writes all the buffers for all file handles owned by the process to 
disk. 


DOSscanEnv 


The DOSscanEnv function searches an environment segment for the 
specified environment variable. The result pointer points at the data 
value of the variable if the search is successful. This function uses the 
following calling syntax: 


rc = DOSscanEnv (pszEnvvarName, pszResultpointer) 


The function provides only one return value (it does provide some 
return parameters discussed in the following paragraphs). rc contains 
a return code that tells you whether the function completed without 
error. It also contains an error code if it didn't. Table 6-33 provides a 
list of these error codes. 


DOSscanEnv function return codes 
Table 6-33 


Error 


number Description 


0 NO ERROR 


203 ERROR ENVVAR NOT FOUND 


This function uses two parameters. pszEnvvarName contains the 
name of the environment variable that you want to retrieve. Do not 
include the trailing equals sign. pszBesultpointer contains a pointer 
to the first character of the environment variable value. 


DOssearchpath 


The DOssearchpath function finds files residing along the specified 
paths. You can use the environment string or supply the path 
directly. This function uses the following calling syntax: 


rc = DOssearchpath (ulcontrol, pszpathRef , pszFileName, 


pbResultBuffer, ulResultBufferLen) 


The function provides only one return value (it does provide some 
return parameters discussed in the following paragraphs). rc contains 
a return code that tells you whether the function completed without 
error. It also contains an error code if it didn't. Table 6-34 provides a 
list of these error codes. 


DOssearchpath function return codes 
Table 6-34 


Error 
number Description 


0 NO ERROR 


1 ERROR INVALID FUNCTION 


2 ERROR FILE NOT FOUND 


87 ERROR INVALID PARAMETER 


111 ERROR BUFFER OVERFLOW 


203 ERROR ENVVAR NOT FOUND 


This function uses five parameters. ulcontrol determines the 
DOssearchpath function behavior. The behavior bits include: 
SEARCH_CUR_DIRECTORY (0), SEARCH_ENVIRONMENT (1), 
SEARCH_IGNORENETERRS (2), and reserved (3 through 31). Each 
bit becomes active when set to one. pszpathBef contains a pointer to 
the search path. If ulcontrol bit 1 is one, then pszpathpef contains 
the name of an environment variable. Otherwise, it contains the 
actual search path. pszFileName contains the ASCIIZ filename. You 
can use wildcard characters for this parameter. If this parameter does 
not contain wildcard characters, then the function returns the 
filename as part of pbBesultBuffer. This allows you to use the 
contents of pbBesultBuffer directly in other functions. 
pbBesultBuffer contains the full path name of the file. 
ulBesultBufferLen contains the length of pbBesultBuffer in bytes. 


Table 6-35 


DOssetcurren+Dir 


The DOssetcurrentDir function sets the current directory. This 
function does not change the current directory if any members of the 
path do not exist. Only the directory of the current process changes. 
This function uses the following calling syntax: 


rc = DOssetcurrentDir (pszDirName) 


The function provides only one return value. rc contains a return 
code that tells you whether the function completed without error. It 
also contains an error code if it didn't. Table 6-35 provides a list of 
these error codes. 


DOssetcurrentDir function return codes 


Error 
number Description 


0 NO ERROR 


2 ERROR FILE NOT FOUND 


3 ERROR PATH NOT FOUND 


5 ERROR ACCESS DENIED 


Error 


number Description 


8 ERROR NOT ENOUGH MEMORY 


26 ERROR NOT DOS DISK 


87 ERROR INVALID PARAMETER 


108 ERROR DRIVE LOCKED 


206 ERROR FILENAME EXCED RANGE 


This function uses one parameter. pszDirName contains the ASCIIZ 
name of the directory path. 


DOssetDefaultDisk 


The DOssetDefaultDisk function sets the specified drive as the 
current drive. This function uses the following calling syntax: 


rc = DOssetDefaultDisk (ulDriveNI]mber) 


The function provides only one return value. rc contains a return 
code that tells you whether the function completed without error. It 
also contains an error code if it didn't. Table 6-36 provides a list of 
these error codes. 


DOssetDefaultDisk function return codes 


Error 
number Description 


0 NO ERROR 


15 ERROR INVALID DRIVE 


This function uses one parameter. ulDriveNumber contains a 1-based 
new default drive number. 


Table 6-37 


DOssetFHstate 


The DOssetFHstate function sets the state of the specified file 
handle. OS/2 does not guarantee that it will write data in any specific 
sector order for multiple sector writes. If you need to write data in a 
specific sector order, then use separate synchronous write operations 
for each sector. You can use this function to return critical error- 
handling control to the system when the application cannot handle it 
by turning off the fail/error bit and reissuing the failed I/0 call. The 
Direct I/0 flag provides physical access to the drive by bypassing the 
FSD. This function uses the following calling syntax: 


rc = DOssetFHstate (hFileHandle, pFileHandlestate) 


The function provides only one return value (it does provide some 
return parameters discussed in the following paragraphs). rc contains 
a return code that tells you whether the function completed without 
error. It also contains an error code if it didn't. Table 6-37 provides a 
list of these error codes. 


DOSQueryFHstate function return codes 


Error 


number Description 


0 NO ERROR 


6 ERROR INVALID HANDLE 


87 ERROR INVALID PARAMETER 


This function uses two parameters. hFileHandle contains the file 
handle that you want to query. pFileHandlestate defines the file 
handle status. Bits 0 through 6 are reserved. Bit 7 contains the 
inheritance flag: a process created by DOSExecprg inherits the flag 
(0) or flag private to the current process (1). Bits 8 through 11 are 
reserved; set it to zero. Bit 12 contains the cache/no-cache flag 
(cache when set to 0). Bit 13 contains the fail errors flag: report 
through the system critical-error handler (0) or report directly to the 
caller (1). Bit 14 contains the write-through flag (write-through mode 


when set to 1). Bit 15 contains the direct open flag: open normally 
(0) or mounted volume to open for direct access (1). 


DOssetFilelnfo 


The DOssetFilelnfo function sets file information. It sets the date 
and time information only when setting level 1 file information on a 
FAT drive. Setting these parameters to 0 does not result in any 
change to the file data. You must open the file with read access and a 
deny-write sharing mode using the DOSopen function before calling 
this function to obtain information at the file information level. This 
function uses the following calling syntax: 


rc = DOssetFilelnfo (hFileHandle, ulFilelnfoLevel, pFilelnfoBuf , 


ulFilelnfoBufsize) 


The function provides only one return value (it does provide some 
return parameters discussed in the following paragraphs). rc contains 
a return code that tells you whether the function completed without 
error. It also contains an error code if it didn't. Table 6-38 provides a 
list of these error codes. 


DOssetFilelnfo function return codes 
Table 6-38 


Error 
number Description 


0 NO ERROR 


1 ERROR INVALID FUNCTION 


5 ERROR ACCESS DENIED 


6 ERROR INVALID HANDLE 


87 ERROR INVALID PARAMETER 


122 ERROR INSUFFICIENT BUFFER 
rl 


124 ERROR INVALID LEVEL 


130 ERROR DIRECT ACCESS HANDLE 


254 ERROR INVALID EA NAME 


255 ERROR EA LIST INCONSISTENT 


This function uses four parameters. hFileHandle contains the file 
handle. ulFilelnfoLevel contains the level of file information you want 
returned: FIL_STANDARD (level 1) or FIL_QUERYEASIZE (level 2). 
pFilelnfoBuf contains the address of the storage area for the file 
information. Each level of returned file information uses a different 
buffer: FILESTATUS3 (level 1) and EAOP2 (level 2). pFilelnfoBufsize 
contains the length of pFilelnfoBuf in bytes. 


Table 6-39 


DOssetFilelocks 


The DOssetFileLocks function locks and/or unlocks a range of bytes 
in an open file. This function uses the following calling syntax: 


rc = DOssetFileLocks (hFileHandle, punlockRange, pLockRange, 


ulTimeout, ulFlags) 


The function provides only one return value. rc contains a return 
code that tells you whether the function completed without error. It 
also contains an error code if it didn't. Table 6-39 provides a list of 
these error codes. 


DOssetFileLocks function return codes 


er Description 


0 NO ERROR 


6 ERROR INVALID HANDLE 


33 ERROR LOCK VIOLATION 


36 ERROR SHARING BUFFER EXCEEDED 


87 ERROR INVALID PARAMETER 


95 ERROR INTERRUPT 


174 ERROR ATOMIC LOCK NOT SUPPORTED 


175 ERROR READ LOCKS NOT SUPPORTED 


This function uses five parameters. hFileHandle contains the file 
handle. punlockpange contains the following fields: Fileoffset 


(LONG) and RangeLength (LONG). pLockBange contains the 
following fields: Fileoffset (LONG) and RangeLength (LONG). 
ulTimeout contains the maximum time that the process should wait 
for the locks in milliseconds. ulFlags determines the action this 
function takes. These bit values include: share when set to 1 (0), 
atomic locking when set to 1 (1), and reserved (2 through 31). 


DOssetFileptr 


The DOssetFileptr function moves the read/write pointer to the 
specified location. A positive distance value moves the pointer 
forward, while a negative value moves the pointer backward. You 
cannot use this function with a character device or pipe. This 
function uses the following calling syntax: 


rc = DOssetFileptr (hFileHandle, 1Distance, ulMoveType, 


pNewpointer) 


The function provides only one return value (it does provide some 
return parameters discussed in the following paragraphs). rc contains 
a return code that tells you whether the function completed without 
error. It also contains an error code if it didn't. Table 6-40 provides a 
list of these error codes. 


DOssetFileptr function return codes 
Table 6-40 


Error 


number Description 


0 NO ERROR 


1 ERROR INVALID FUNCTION 


6 ERROR INVALID HANDLE 


130 ERROR DIRECT ACCESS HANDLE 


131 ERROR NEGATIVE SEEK 


132 ERROR SEEK ON DEVICE 


This function uses five parameters. hFileHandle contains the file 
handle. IDistance contains the distance to move the read/write 


pointer in bytes. ulMoveType determines the location of the start 
position within the file: FILE_BEGIN (0), FILE_CURRENT (1), or 
FILE_END (2). pNewpointer contains the address of the read/write 
pointer location. 


-:i: ----- _-=':= _ 


Table 6-41 


DOssetFilesize 


The DOssetFilesize function changes the size of a file. You must 
open the file in a mode that allows write access before you issue this 
function. This function allows you to extend or truncate a file. OS/2 
tries to allocate space in a contiguous or near contiguous space on 
the hard drive when you extend the file. This function uses the 
following calling syntax: 


rc = DOssetFilesize (hFileHandle, ulFilesize) 


The function provides only one return value. rc contains a return 
code that tells you whether the function completed without error. It 
also contains an error code if it didn't. Table 6-41 provides a list of 
these error codes. 


DOssetFilesize function return codes 


Error 
number Description 


0 NO ERROR 


5 ERROR ACCESS DENIED 


6 ERROR INVALID HANDLE 


26 ERROR NOT DOS DISK 


33 ERROR LOCK VIOIATION 


87 ERROR INVALID PARAMETER 


112 ERROR DISK FULL 


This function uses two parameters. hFileHandle contains the handle 
of the file that you want to change. ulFilesize contains the new file 
size in bytes. 


DOssetFslnfo 


The DOssetFslnfo function sets information for a file system device 
(FSD). It does not return trailing blanks in the volume label. You must 
open the volume in a mode that allows write access to use this 
function. This function uses the following calling syntax: 


rc = DOssetFslnfo (ulDriveNIJmber, ulFslnfoLevel, pFslnfoBuf , 


ulFslnfoBufsize) 


The function provides only one return value. rc contains a return 
code that tells you whether the function completed without error. It 
also contains an error code if it didn't. Table 6-42 provides a list of 
these error codes. 


DOssetFslnfo function return codes 
Table 6-42 


Error 
number Description 


0 NO ERROR 


15 ERROR INVALID DRIVE 


82 ERROR CANNOT MAKE 


122 ERROR INSUFFICIENT BUFFER 


123 ERROR INVALID NAME 


124 ERROR INVALID LEVEL 


154 ERROR IABEL TOO LONG 


This function uses four parameters. ulDriveNumber contains a 1- 
based number of the drive you want to change. A value of 0 uses the 
current drive. A value of OxFFFF indicates that pFslnfoBuf contains 
the ASCIIZ path name of the FSD. ulFslnfoLevel contains the level 
of file information you want to set (2 is the only valid value). 
pFslnfoBuf contains the new file system information. The bytes in 
this parameter include: length of the volume label in bytes (1) and the 
ASCIIZ volume label name (2 through end of string). ulFslnfoBufsize 
contains the length of pFslnfoBuf in bytes. 


___----__:-- 


Table 6-43 


DOssetMaxFH 


The DOssetMaxFH function defines the maximum number of file 
handles that the calling process can use. The default setting is 20. 
This function preserves all open file handles when it increases the 
maximum number of file handles. This function uses the following 
calling syntax: 


rc = DOssetMaxFH (ulNImberHandles) 


The function provides only one return value. rc contains a return 
code that tells you whether the function completed without error. It 
also contains an error code if it didn't. Table 6-43 provides a list of 
these error codes. 


DOssetMaxFH function return codes 


Error 


number Description 


0 NO ERROR 


8 ERROR NOT ENOUGH MEMORY 


87 ERROR INVALID PARAMETER 


This function uses one parameter. ulNumberHandles contains the 
total number of handles your application requires. 


DOssetpathlnfo 


The DOssetpathlnfo function sets the information for a file or 
directory. You must open the file or directory object in exclusive write 
mode to use this function. Providing a value of 0 in the time and date 
field components leave those values unchanged. OS/2 modifies the 
last modification date and time if you change the extended attributes. 
This function uses the following calling syntax: 


rc = DOssetFilelnfo (pszpathName, ulFilelnfoLevel, pFilelnfoBuf , 


ulFilelnfosize, ulpathlnfoFlags) 


The function provides only one return value. rc contains a return 
code that tells you whether the function completed without error. It 
also contains an error code if it didn't. Table 6-44 provides a list of 
these error codes. 


DOssetpathlnfo function return codes 


Error 
number Description 


0 NO ERROR 


32 ERROR SHARING VIOLATION 


87 ERROR INVALID PARAMETER 


122 ERROR INSUFFICIENT BUFFER 


124 ERROR INVALID LEVEL 


206 ERROR FILENAME EXCED RANGE 


254 ERROR INVALID EA NAME 


255 ERROR EA LIST INCONSISTENT 


This function uses five parameters. pszpathName contains the 
ASCIIZ full path name of the file or directory that you want to 
modify. You cannot use wildcard characters with this function. 
ulFilelnfoLevel determines the level of directory information you 
define: FIL_STANDARD (level 1) or FIL_QUERYEASIZE (level 2). 
pFilelnfoBuf contains the new directory information. Each 
information level uses its own structure: FILESTATUS3 (level 1) or 
EAOP2 (level 2). ulFilelnfosize contains the length of pFilelnfoBuf in 
bytes. dlpathlnfoFlags controls how DOssetFilelnfo writes the data 
to disk. A value of DSPI WRTTHRU sends the information to disk 
immediately. 


DOssetRelMaxFH 


The DOssetRelMax function changes the maximum number of file 
handles for the calling process. This function preserves all open file 
handles. As a result, OS/2 might defer or disregard a request to 


reduce the number of file handles for the current process. This 
function uses the following calling syntax: 


rc = DOssetRelMaxFH (pReqcount, pcurMaxFH) 


The function provides only one return value. rc contains a return 
code that tells you that the function completed without error. There 
are no error codes associated with this function. 


This function uses two parameters. pBeqcount contains the number 
of handles that you want to add the current number of handles. A 
negative value decreases the current handle count, while a positive 
number increases it. pcurMaxFH contains the new maximum number 
of file handles on exit. 
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DOssetverify 


The DOssetverify f,unction sets write verification. The operating 
systems verify all disk writes when you activate verification. This 
function uses the following calling syntax: 


rc = DOssetverify (f32Verifysetting) 


The function provides only one return value. rc contains a return 
code that tells you whether the function completed without error. It 
also contains an error code if it didn't. Table 6-45 provides a list of 
these error codes. 


DOssetverify function return codes 


Error 


number Description 


0 NO ERROR 


118 ERROR INVALID VERIFY SWITCH 


This function uses one parameter. f32Verifysetting contains the state 
of the verify mode. A value of 1 activates verify mode. 


DOsshutDown 


The DOsshutDown function locks out all changes to file systems and 
writes the contents of the system buffers to disk in preparation for 
system shutdown. This function can take several minutes to complete 
depending on the contents of the system buffers. You cannot allocate 
memory once this function is issued. This means that you must 
allocate any required memory before issuing this function. This 
function uses the following calling syntax: 


rc = DOsshutDown (ulReserved) 


The function provides only one return value. rc contains a return 
code that tells you whether the function completed without error. It 
also contains an error code if it didn't. Table 6-46 provides a list of 
these error codes. 


DOsshutdown function return codes 
Table 6-46 


Error 


number Description 


0 NO ERROR 


87 ERROR INVALID PARAMETER 


274 ERROR ALREADY SHUTDOWN 


This function uses one parameter. ulBeserved is a reserved DWORD 
value; set it to 0. 


DOswrite 


The DOswrite function writes a specified number of bytes from a 
buffer to the specified file. It always begins writing at the current file 
pointer position. You can use the DOssetFileptr function to change 
the position of the file pointer prior to calling this function. OS/2 
automatically updates the file pointer after it writes the data. This 
function automatically fails if you attempt to write to a read-only file 
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or if the target drive does not contain enough space. This function 
uses the following calling syntax: 


rc = DOswrite (hFileHandle, pBufferArea, ulBufferLength, 


pByteswritten) 


The function provides only one return value (it does provide some 
return parameters discussed in the following paragraphs). rc contains 
a return code that tells you whether the function completed without 
error. It also contains an error code if it didn't. Table 6-47 provides a 
list of these error codes. 


DOswrite function return codes 


Error 


number Description 


0 NO ERROR 


5 ERROR ACCESS DENIED 


6 ERROR INVALID HANDLE 


19 ERROR WRITE PROTECT 


26 ERROR NOT DOS DISK 


29 ERROR WRITE FAULT 


33 ERROR LOCK VIOIATION 


109 ERROR BROKEN PIPE 


This function uses four parameters. hFileHandle contains the file 
handle you obtained using the DOSopen function. pBufferArea 
contains the address of a buffer that holds the information that you 
want to write. ulBufferLength contains the length of pBufferArea. 
pByteswritten contains the actual number of bytes written to disk. 


DOSDevloctl functions 


You access both the physical and logical disk access methods provided 
by OS/2 using the DOSDevloctrl function that I originally outlined in 
chapter 4. You might want to refer to this chapter if you don't already 


granRE 


know how to use this function. Chapter 4 provides complete 
information on the call and parameter information required to use 
the DOSDevloctl function. Fortunately, each call to the function 
follows the same format; only the values of the parameters change 
from call to call. Each call can provide error information in addition 
to the generic error information provided in chapter 4. 


As previously stated, there are three groups (types) of information 
required to use the DOSDevloctl function. The first group is the call 
definition. This should not change from implementation to 
implementation. Each vendor should define the calls using the same 
defines. If not, you probably will need to check the vendor-supplied 
header files and handle any differences yourself . One difference 
between disk access and other device access is that you use the 
DOsphysicalDisk function (described at the beginning of this chapter) 
to obtain a handle for physical disk access. Do not use this function 
to get a handle for logical disk access. 


The other two groups of information are the parameters required to 
use the function. Some texts call the first set of parameters the 
poramefer pc[ckef and the second set the data packet. Other texts 
use different terms. This text uses the simple terminology poromefer 
I.n/ormo£!.on and dafo I.n/ormof I.on to differentiate the two sets of 
information. Make sure that you understand the difference so that 
you can cross reference the information in this book with any 
information provided by your compiler vendor. Because IBM does not 
provide in-depth documentation for this information in OS/2 
versions 2.0 and above, you more than likely will see differences in 
terminology from vendor to vendor. In addition, your compiler vendor 
might add functions not directly addressed by the generic functions in 
this book. Always double-check the DOSDevloctl implementation 
used by your compiler vendor. 


The following paragraphs concentrate on the generic logical and 
physical disk functions, but it always pays to search the hard disk 
vendor documentation and any INI files on your system. Most hard 
disks will not require INI files, but it never hurts to check. You might 
want to check the device drivers themselves for additional 
information (provided the software licensing agreement does not 
prevent this action). Some vendors might even sell a developer's kit 


or other form of formal documentation for their device driver. Don't 
stop with the disk drive vendor either. Make sure that you check with 
the controller manufacturer as well. Some controllers provide 
advanced features that you can access only using the DOSDevloctl 
calls. For example, Adaptec controllers provide a special ASPI 
interface for tape drives connected to their SCSI controllers. 


DSK functions 


The DSK functions control logical access to the hard disk drive. 
Remember, the DOSDevloctl functions provide you with low-level 
access to the hard disk. You could just as easily use one of the many 
WIN or GPI functions within a PM application (a device context can 
be any device including the hard disk). The DOS functions described 
in the previous sections also provide a viable alternative to using 
these functions. The reason that you want to use DOSDevloctl is the 
need for lower-level access than you can get using these standard 
functions. On the other hand, the logical disk functions still provide a 
level of abstraction from the physical disk functions. 


The Borland compiler provides access to the DSK functions through 
the BSEDEV.H and BSEDOS.H include files. Look in the BSEERR.H 
file for a complete list of error codes associated with these functions. 
The BSEDEV.H file contains the entries that you need to actually use 
the DOSDevloctl function. The BSEDOS.H file contains the 
DOSDevloctl function declaration. Both files provide interesting bits 
of information. You might need to check the include files for your 
compiler to find references to these functions because most vendors 
do not document them. In some cases, the vendor uses a new name 
for the function. Fortunately, most vendors include a file with 
#defines that allow you to use the original names. Table 6-48 
provides a complete list of the logical disk DOSDevloctl functions. 


NOTE |°oSc/ti pvaecrks::sn. i.s°aa:edsuL)i| t::Vkceernd:ivde::sd:onto:aus:dtirestand generic 


ulDataLengthMax, pDataLengthlnout, ulparmLengthMax, and 
pparmLengthlnout parameters to the device driver. You must mark 
device drivers level 2 or higher to support receipt of these fields. 


DOSDevloctl logical disk generic functions Table 6-48 


Function Name Description 


Logical Disk IOctl Commands (Category 8) 


OxOOOO Lock Drive This function locks a drive. You use it to exclude another 


process from using the volume from I/0. It succeeds only 
if the only file handle open on the drive is the one that 
issues the lock drive call. The parameter information 
includes command information (BYTE). This is a reserved 
field, set it to 0. The data information includes a reserved 
field (BYTE). 


OxOoo 1 Unlock Drive 


Ox0002 
Redetermine 
Media 


This function unlocks a drive previously locked using 
function OxOOOO. The parameter information includes 
command information (BYTE). This is a reserved field, set 
it to 0. The data information includes a reserved field 
(BYTE). 


This function rebuilds the device parameters including the 
volume parameter block ovpB) used by the operating 
system to identify the drive. It accomplishes this by 
simulating a close of the current device handle and 
remounting the volume. This includes detaching the old 
FSD and attaching a new one. Always lock the volume 
using function OxOOOO before calling this function. The 
parameter information includes command information 
(BYTE). This is a reserved field, set it to 0. The data 
information includes a reserved field (BYTE). 


Ox0003 Set Logical Map This function sets the next logical drive letter used to 


reference the drive. You can determine the last logical 
drive letter assigned to the physical drive using function 
Ox0021. The parameter information includes command 
information (BYTE). This is a reserved field, set it to 0. 
The data information includes a 1-based logical drive 
number on entry (BYTE). It contains the logical drive 
current mapped to the physical drive that uses the 
specified file handle on return. The parameter contains a 
zero if there is only one logical drive mapped onto this 
physical drive. 


Ox0004 Begin Format 
This function mounts (attaches) the specified FSD to a 
logical disk volume. You normally use this function to 
force mount the FSD that formats the volume. The 
function automatically dismounts any current FSD. Using 
this function also sets a flag in the operating system 
kernel. The parameter information includes the ASCIIZ 
FSD name. A zero length string forces OS/2 to use the 
FAT file system. The data information includes command 
information (BYTE). This is a reserved field, set it to 0. 
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Function Name 


Ox0020 Block Removable 


Ox0021 


Ox0043 


Query Logical 
Map 


Set Device 
Parameters 


Description 


This function determines if the media is removable or 
fixed. The parameter information includes: command 
information (BYTE) and drive unit (BYTE). The command 
information is a reserved field, set it to 0. The drive unit 
contains a 0-based drive number. The data information 
includes the data field (BYTE). A return value of 0 
indicates removable media. 


This function returns the drive number last used to 
reference the logical drive. The parameter information 
includes command information (BYTE). This is a reserved 
field, set it to 0. The data information includes a 1-based 
logical drive number (BYTE). It returns zero if there is only 
one drive letter. 


This function sets the drive parameters. The parameter 
information includes: command information (BYTE) and 
drive unit (BYTE). The first two bits of the command 
information determine what action this function takes: 
build BPB from the medium for all subsequent Build BPB 
functions (00b), change the default BPB for the device 
(01b), or change BPB for the medium to the specified 
BPB (lob). Set all other bits of this field to 0. The drive 
unit is a 0-based drive number. The data information 
includes: extended BPB for devices (31 BYTES), number 
of cylinders (WORD), device type (BYTE), and device 
attributes (WORD). The device type includes the following: 
48 TPI diskette drive (0), 96 TPI diskette drive (1), 720K 
drive (2), 8-inch single density floppy (3), 8-inch double 
density floppy (4), fixed disk (5), tape drive (6), other 
(includes 1.44MB diskette) (7), R/W optical disk (8), and 
2.88MB diskette (9). The device attribute bits include: 
removable media flag (0 = removable) (0) and changeline 
flag (1 = device supports changeline) (1). Set all other bits 
to 0. The extended BPB structure includes the following 
elements: 
Length Description 


WORD Bytes per sector 


BYTE Sectors per cluster 


WORD Reserved sectors 


BYTE Number of FATs 


WORD Root directory entries 


WORD Total sectors 


Function Name 


Ox0044 Write Track 


Ox0045 
Format and 
Verify Track 


Description 
Length Description 


BYTE Media descriptor 


WORD Sectors per FAT 


WORD Sectors per track 


WORD Number of heads 


DWORD Hidden sectors 


DWORD Large total sectors 


6 BYTES Reserved 


This function writes a track of information. The parameter 
information includes: command information (BYTE), head 
(WORD), eylinder (WORD), first sector (WORD), number of 
sectors (WORD), and track layout table (BYTES). The 
command information contains a 0 in bit 0 if the track layout 
consists of nonconsecutive sectors or does not start with 
sector 1 . The data information contains the data packet 
buffer. This contains the information you want to write to the 
disk. The track layout table has the following format: 
Length D escription 


WORD Sector number for sector 1 


WORD Sector size for sector 1 


WORD Sector number for sector 2... 


WORD Sector size for sector 2... 


WORD Sector number for sector N (one entry for 


each sector) 


WORD Sector size for sector N (one entry for each 


sector) 


This function formats and verifies the track contained in 
the track layout field. The controller performs the actual 
format based on the contents of this field. The parameter 
information includes: command information (BYTE), head 
WORD), cylinder WORD), number of tracks OvORD), 
number of sectors (WORD), and track layout table 
(BYTES). The command information contains a 0 in bit 0 
if the track layout consists of nonconsecutive sectors or 
does not start with sector 1. The format track table is a 
series of four byte tuples. Each tuple contains the cylinder 
number, head number, sector ID, and bytes per sector. 
The bytes per sector values include: 128 (0), 256 (1), 512 
(2), and 1024 (3). The data information contains the 
starting sector on entry (BYTE). It contains the first bad 
sector (if any) on return from a multi-track format. 
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Function Name 


Ox0060 Query Media 


Sense 


Ox0063 Query Device 


Parameters 


Description 


This function returns the media sense information. The 
parameter information includes command information 
(BYTE). This is a reserved field, set it to 0. The data 
information includes the media sense information (BYTE). 
This contains one of the following values: unable to 
determine media (0), 720K diskette (1), 1.44MB diskette 
(2), or 2.88MB diskette (3). This function returns the 
following error codes: 


Error 


number Description 


0 NO ERROR 


1 ERROR INVALID FUNCTION 


6 ERROR INVALID HANDLE 


15 ERROR INVALID DRIVE 


22 ERROR BAD COMMAND 


31 ERROR GEN FAILURE 


87 ERROR INVALID PARAMETER 


115 ERROR PROTECTION VIOLATION 


117 ERROR INVALID CATEGORY 


119 ERROR BAD DRIVER LEVEL 


163 ERROR UNCERTAIN MEDIA 


165 ERROR MONITORS NOT SUPPORTED 


This function returns the parameters for the specified 
device. The parameter information includes: command 
information (BYTE) and drive unit (BYTE). The command 
information contains a 0 in bit 0, if you want the function 
to return the recommended BPB for the drive, or 1, if you 
want it to return the current BPB for the drive. The drive 
unit contains a 0-based drive number. The data 
information includes: extended BPB for device (see 
function Ox0043) (31 BYTES), number of cylinders 
(WORD), device type (BYTE), and device attributes 
(WORD). The device type includes the following: 48 TPI 
diskette drive (0), 96 TPI diskette drive (1), 720K drive (2), 
8-inch single density floppy (3), 8-inch double density 
floppy (4), fixed disk (5), tape drive (6), other (includes 
1.44MB diskette) (7), R/W optical disk (8), and 2.88MB 
diskette (9). The device attribute bits include: removable 


Function Name 


Ox0064 Read Track 


Ox0065 Verify Track 


Description 


media flag (0 = removable) (0) and changeline flag (1 = 
device supports changeline) (1). 


This function reads a track of information. The parameter 
information includes: command information (BYTE), head 
(WORD), cylinder (WORD), first sector (WORD), number of 
sectors (WORD), and track layout table (BYTES). The 
command information contains a 0 in bit 0 if the track 
layout consists of nonconsecutive sectors or does not start 
with sector 1. Refer to function Ox0044 for the layout of 
the track layout table. The data information contains the 
data packet buffer. This contains the information you want 
to write to the disk. 


This function verifies a track of information. The parameter 
information includes: command information (BYTE), head 
(WORD), cylinder (WORD), first sector (WORD), number of 
sectors (WORD), and track layout table (BYTES). The 
command information contains a 0 in bit 0 if the track 
layout consists of nonconsecutive sectors or does not start 
with sector 1. Refer to function Ox0044 for the layout of 
the track layout table. There is no data information. 


Using this table is quite simple. The previous paragraphs describe the 
calling syntax for this function. You obtain hDevHandle using an 
open call. The ulcategory entry appears in the heading for each 
group of function calls. The ulFunction entry appears in the first 
column of the table. The rest of the entries (pparmList, 
ulparmLengthMax, pparmLengthlnout, pDataArea, 
ulDataLengthMax, and pDataLengthlnout) appear in the function 
description in chapter 4. You need to provide the specifics required 
to make these functions work. 


PDSK functions 


The PDSK functions control physical access to the hard disk drive. 
This is different from logical access. There is only one physical drive. 
That one physical drive could contain many logical drives. A logical 
drive is not necessarily a partition. What it includes are all the drive 
letters that the machine supports. The physical drive is the base 
drive; the entire physical entity. This is an important distinction. 
When you use the function described in the following sections, you 
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are gaining access to the physical drive. This drive includes a lot more 
than simply data; it includes the partition and other information as 
well. As you can see, the PDSK functions provide a much lower level 
of disk access than any of the other functions discussed so far. They 
provide the lowest level of access you can get to the disk drive. 


Always use the logical disk functions to access the drive whenever 
possible. The physical disk functions in this section of the chapter 
provide the lowest level access to the drive that you can achieve using 
OS/2 (short of writing your own device driver). Improper use of these 
functions could damage the drive and your data. 


The Borland compiler provides access to the PDSK functions through 
the BSEDEV.H and BSEDOS.H include files. Look in the BSEERR.H 
file for a complete list of error codes associated with these functions. 
The BSEDEV.H file contains the entries that you need to actually use 
the DOSDevloctl function. The BSEDOS.H file contains the 
DOSDevloctl function declaration. Both files provide interesting bits 
of information. You might need to check the include files for your 
compiler to find references to these functions because most vendors 
do not document them. In some cases, the vendor uses a new name 
for the function. Fortunately, most vendors include a file with 
#defines that allow you to use the original names. Table 6-49 
provides a complete list of the physical disk DOSDevloctl functions. 


DOSDevloctl physical disk generic functions 


Function Name Description 


Physical Disk IOctl Commands (Category 9) 


OxOOOO 


OxOOO1 


Lock Physical 
Drive 


Unlock Physical 
Drive 


This function locks the physical drive. The parameter 
information includes command information (BYTE). This 
is a reserved field, set it to 0. The data information 
includes a reserved field (BYTE). 


This function unlocks a physical drive previously locked 
using function OxOOOO. The parameter information 
includes command information (BYTE). This is a reserved 
field, set it to 0. The data information includes a reserved 
field (BVIE). 


Function Name 


Ox0044 Write Track 


Ox0063 
Query Device 
Parameters 


Ox0064 Read Track 


Ox0065 Verify Track 


Description 


This function writes a track of information. The parameter 
information includes: command information (BYTE), head 
OvORD), cylinder OvORD), first sector OvORD), number 
of sectors (WORD), and track layout table (BYTES). The 
command information contains a 0 in bit 0 if the track 
layout consists of nonconsecutive sectors or does not start 
with sector 1. The data information contains the data 
packet buffer. This contains the information that you want 
to write to the disk. The track layout table has the 
following format: 
Length Description 


WORD Sector number for sector 1 


WORD Sector size for sector 1 


WORD Sector number for sector 2... 


WORD Sectorsize forsector 2... 


WORD Sector number for sector N (one entry for each 


sector) 


WORD Sector size for sector N (one entry for each 


sector) 


This function returns the parameters for the specified 
device. The parameter information includes the command 
information (BYTE). This is a reserved field, set it to 0. 
The data information includes: reserved field (WORD), 
number of cylinders (WORD), number of heads (WORD), 
number of sectors per track (WORD), reserved field 
OvORD), reserved field OvORD), reserved field OvORD), 
and reserved field (WORD). 


This function reads a track of information. The parameter 
information includes: command information (BYTE), head 
OvORD), cylinder OvORD), first sector (WORD), number 
of sectors OvORD), and track layout table (BYTES). The 
command information contains a 0 in bit 0 if the track 
layout consists of nonconsecutive sectors or does not start 
with sector 1. Refer to function Ox0044 for the layout of 
the track layout table. The data information contains the 
data packet buffer. This contains the information 
that you want to write to the disk. 


This function verifies a track of information. The 
parameter information includes: command 
information (BYTE), head OvORD), cylinder 
(WORD), first sector (WORD), number of sectors 
OvORD), and track layout table (BYTES). The 
command information contains a 0 in bit 0 if the 
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Function Name Description 


track layout consists of nonconsecutive sectors 
or does not start with sector 1 . Refer to function 
Ox0044 for the layout of the track layout table. 
There is no data information. 


OS/2 Version 1.0 and 1.1 device drivers do not understand generic 
IOctl packets. As a result, the kernel does not pass the 
ulDataLengthMax, pDataLengthlnout, ulparmLengthMax, and 
pparmLengthlnout parameters to the device driver. You must mark 
device drivers level 2 or higher to support receipt of these fields. 


Using this table is quite simple. The previous paragraphs describe the 
calling syntax for this function. You obtain hDevHandle using an 
open call. The ulcategory entry appears in the heading for each 
group of function calls. The ulFunction entry appears in the first 
column of the table. The rest of the entries (pparmList, 
ulparmLengthMax, pparmLengthlnout, pDataArea, 
ulDataLengthMax, and pDataLengthlnout) appear in the function 
description in chapter 4. You need to provide the specifics required to 
make these functions work. 


EEBEREfflffiREffiEE3ma 


ERSION 2.1 of OS/2 introduces multimedia extensions 
similar to those found in Windows NT and Windows 3.1 


Users can attach sounds to specific events and use their computer to 
play CDs or MIDI files. This is the minimum that most users expect 
from their sound system. OS/2 adds the capability to work with full- 
motion video-a real bonus for the user. Fortunately for OS/2 users, 
you can fully exploit these new capabilities in an application without 
too much effort. This means that you can create a fully functional 
multimedia application without investing in additional toolkits or 
libraries. 


This chapter covers the use of OS/2's multimedia extensions in 
REXX applications. It also looks at using these capabilities within a 
standard C application. Both types of programming use what OS/2 
includes in the standard version without any additional tools. The last 
section of the chapter looks at what you could do with IBMs 
Multimedia Toolkit. This provides you with some ideas on what you 
can do with a standard installation versus a multimedia enhanced 
installation. In either case, OS/2 provides you with everything you 
need to exploit the multimedia environment. 


The chapter takes a Presentation Manager application approach. It is 
very unlikely that anyone would want to write a character-mode 
multimedia application. After all, PM provides all the graphics 
capability that you need as a built-in feature. Why waste the effort 
required to duplicate this capability in a character-mode application? 
Most of the coding samples will concentrate on the sound board and 
CD-ROM drive because these are the two components most 
programmers need to include in their applications. 


Understanding the 
Media Control Interface (MCI) 


The media control interface (MCI) is a set of controls that you can 
use with most of the components of your multimedia system. Think 
of it as the remote control unit for your home stereo system. Every 
command is a button push on the remote control. This remote 
control actually takes the form of string commands, but it really helps 


to think about it as a physical remote control device. You also need to 
look at the system connections much like your stereo system. Each 
device is a modular component that you mixed and matched with 
your computer system to create a multimedia environment. 


The command structure for a string command is fairly simple. Every 
command can contain up to four components: command, object, 
keyword (or items), and wait. The command string appears as 
follows: 


C'ommancz Object [Ke];words/rtems] [Wait] 


Think about the remote control again. The command is the button 
that you push on the remote control. For example, you might push 
the play button. Some of the MCI commands are a little more 
esoteric than this. They include commands like acquire, capability, 
and info in addition to the more familiar commands like play. 


The object part of the command string is the device you point at: 
videotape, videodisc, CDaudio, waveaudio, sequencer, or digitalaudio. 
There are a few additions to this as well. For example, you could 
point at a file instead of a device. MMPM/2 looks at the extension of 
the file to determine which device it belongs to. This might not work 
very well if you use nonstandard extensions for the filenames. 
MMPM/2 also provides the means for using a device name or an 
alias. A device name takes the form DevicetypeNN, where NN is a 
number starting with 01. You can use the device name option to poll 
a system and return the types of devices that OS/2 recognizes. This 
is especially useful when you have more than one of a specific device 
type or you are unsure of what devices the host machine supports. 
The alias option works with the open command. It allows you to 
reuse the device identifier later. 


The two remaining parts of a command string are optional. A 
keyword modifies the command. For example, think of a 
multipurpose remote control for a moment. Some of the keys 
perform one task when used with one device and a totally different 
function when used with another device. The keywords work much 
this way. They modify the command and enhance its usefulness. 
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The wait part of a command string also is optional. It simply tells 
OS/2 to wait until it completes one command before it attempts to 
process the next one. Think of the havoc that would result if you tried 
to push several buttons on your remote control simultaneously. We all 
use our remote control buttons one at a time; waiting to see the effect 
of the button push before pushing the next one. The wait parameter 
of a coinmand string allows OS/2 to do the same thing. You can 
obtain much faster reactions with multiple devices by issuing the 
commands in sequence without a wait added. This is why the wait 
parameter is a command string option. 


Now that you have the basic idea of how to use a command string, it's 
time to look at what tasks the MCI allows you to perform. Table 7-1 
provides a complete listing of the MCI commands. Notice that each 
command follows the format outlined in the previous paragraphs. 


MCI command reference 


Command Items 


Acquire 


Capability 


Exc I usive-Obtains exclusive use 
of all resources associated with 
the object. OS/2 blocks other 
applications until you issue the 
release command. 


Exclusive instance-Obtains 
exclusive use of only the 
resources required by your 
application. Other applications 
can use the device as long as 
such use does not interfere with 
your application. 
Queue-Requests to use 
resources associated with an 
object. The function waits until an 
application finishes using the 
resources before returning. 


This list contains the most 
common device items. Some 
devices provide other capabilities. 
The following items return TRUE 
if the device supports this 
capability: 


Description 


This command provides access to a 
particular device. It allows you to gain 
use of the device exclusive or in 
conjunction with other applications. 
The default settings allow other 
applications to access the device. 


This command provides information 
about the capabilities of a device. For 
example, you may want to know if a 
device can both playback and record. 
Use the DeviceNN where NN is a device 
number object with this command to 
individually poll each device on the 


Command Items 


Can record 
Has audio 
Has video 
Can eject 
Can play 


Close 


Connector 


Can save 
Uses files 
Can lockeject 
Can setvolume 


Compound device-Returns 
true if the device requires an 
element name. 


Preroll type-Returns one of 
three values depending on the 
device's preroll type. Notified 
means the device preroll time is 
variable. Deterministic means 
that the device preroll time is 
fixed. None means the device 
does not support preroll. 


Preroll time-Returns the device 
preroll time. 
Device type-Returns one of the 
following: animation, ampmix, 
cdaudio, cdxa, digitalvideo, 
overlay, sequencer, videodisc, 
waveaudio, or other. 


Message item-Returns true if 
the device supports the messages 
specified by item. 


There are no items associated 
with this command. 


There are three actions that you 
can perform. All three usually 
require that you supply the 
number and/or type items. 


Enable-This action starts the 
flow of information through the 
connector. 


Disable-This action stops the 
flow of information through the 
connector. 


Query-This action returns true 
if the connector is enabled or 


Description 


machine. This allows you to build a 
capabilities list for each machine before 
you attempt to implement various parts 
of your application. Always use the 
WAIT keyword with this function. 


This command closes the device context 
and frees any resources. Use the same 
object to close as you used when 
opening the device context. 


This command enables, disables, or 
queries the status of device connectors. 
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Command Items 


Info 


Load 


Open 


false if it is disabled. 


You can use the following items 
to modify this command: 


Number connector_ number- 
The command assuries that you 
want to perform the action on 
the first connector unless you 
supply this item. 
Type connector_types 
Determines which type of 
connector you want to operate 
on. These types include: MIDI 
stream, CD stream, wave stream, 
RA stream, amp stream, 
headphones, speakers, 
microphone, line in, line out, 
video in, and video out. 


There are no items associated 
with this command. 


Filename-Name of the file that 
you want to load into the device 
context. Using the NEW reserved 
filename opens an untitled file 
that you can save using the Save 
option of the File menu or the 
Save command (discussed later). 


Shareable-Opens the device 
context as a shareable device. 
This allows other device contexts 
(usually applications) to use the 
device. 


Type dev/.oeJyperDetermines 
the compound device used to 
control a device element. If you 
don't specify a type, the MCI 
automatically determines the 
device type using the file's 
extension. 


Alias clev/.ce a//.as-Defines an 
alternate nar=e for the device. 


Description 


This command returns a string 
containing the product information 
associated with the object. 


This command loads a new device 
element into a previously opened device 
context. Always use a PMREXX session 
to run digital video files. 


This command opens a device context 
using the specified object. It opens a 
value called the Device ID, which 
identifies the device context. 


Command Items 


Use this alternate name in 
subsequent commands to identify 
a specific device context. The 
Open command uses this item 
as storage for the Device ID that 
it returns. 


Pause 


Play 


Record 


Release 


There are no items associated 
with this command. 


From pos-Determines the 
starting playing position. Omitting 
this item starts play at the current 
position. 
To pos-Determines the ending 
playing position. Omitting this 
item stops the device at the end 
of file or other media. 


I nsert-Allows you to add data to 
the device element starting at the 
specified or current position. This 
is the default setting on devices 
like hard disks that support data 
insertion. The command returns 
an error if the device does not 
support insertion. 


Overwrite-Allows you to replace 
the current data in the device 
element. This is the default setting 
on devices like video tape that do 
not support data insertion. 


From pos-Determines the 
starting recording position. 
Omitting this item starts recording 
at the current position. 


To pos-Determines the ending 
recording position. Omitting this 
item stops the device at the end 
of file or other media. 


There are no items associated 
with this command. 


Description 


This command momentarily stops a 
device from playing. The actual 
difference between this command and 
the Stop command is device dependent. 
In most cases, the Pause command 
allows you to restart play at the position 
where you stopped. It also can reduce 
the device latency time. 


This command starts playing the device 
or file. 


This command starts data recording (if 
the device supports it). The default 
setting starts recording at the current 
position. Some devices like video tape 
do not support data insertion. This 
command defaults to data overwrite in 
this case. 


This command releases the device 
context; telling MMPM/2 that you no 
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Command Items 


Resume 


Save 


Seek 


Set 


F}eturn resource-This keyword 
returns device control to the last 
application which lost it. 


There are no items associated 
with this command. 


There are no items associated 
with this command. 


You can specify a filename. This 
determines the name of the file 
used to store the information. 
MCI automatically uses the 
existing filename if you do not 
supply one. You can include a 
path with this parameter. MCI 
requires a filename for an untitled 
file. 


To pos-Determines the ending 
recording position. Omitting this 
item stops the device at the end 
of file or other media. 


To start-Stops at the beginning 
of the media or file. 


To end-Stops at the end of the 
media or file. 


Audio [all i left: right] [volume 
percenfage] [on : off] [over 
ml.Ill.seconds|-Theree[refour 
groups of audio settings. The 
first affects which channel you 
control. The second affects the 
volume level. The third turns the 
channel on or off . The fourth 
determines the amount of time 
required to enact the change. 


Door closed-Retracts the tray 
and closes the door. 


Door open-Opens the door and 
extends the tray. 


Description 


longer require the device. You do not 
necessarily lose device control when 
executing this command. 


This command resumes playing of a 
paused device. It keeps the previous 
settings in force. 


This command saves the data 
associated with a device. 


This command finds the specified 
position and stops the device. 


This command establishes the device 
settings. 


Command Items 


Door locked-Locks the door so 
that you cannot open it manually. 


Door unlocked pos-Unlocks 
the door so that you can open it 
manually. 


Master MIDl-Selects the MIDI 
sequencer as the synchronization 
source. MCI outputs the data in 
MIDI format. The IBM sequencer 
does not support this option. 


Master none-Deselects all 
synchronization sources. The IBM 
sequencer does not support this 
Option. 


Master SMPTE-Selects the MIDI 
sequencer as the synchronization 
source. MCI outputs the data in 
SMPTE format. The IBM 
sequencer does not support this 
Option. 


Slave file-This is the default 
setting for the synchronization 
source. The MIDI sequencer uses 
a file for synchronization data. 


Slave MIDl-Selects the MIDI file 
as the synchronization source. 
The MIDI sequencer uses this data 
with the incoming data. The 
sequencer recognizes 
synchronization data with the 
MIDI format. The IBM sequencer 
does not support this option. 


Slave none-Deselects all sources 
of MIDI synchronization data. 


Slave SMPTE-Selects the 
incoming MIDI data as the 
synchronization source. The 
sequencer recognizes 
synchronization data with the 
SMPTE format. The IBM 
sequencer does not support this 
Option. 


Time format milliseconds (or 


Description 
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Command Items 


ms)-Sets the time format to 
milliseconds. 


Status 


Stop 


Time format MMTIME-Sets the 
time format to MMTIME (3000 
units per second). 


Speed format percentage-Sets 
the speed format to percentage. 


Speed format fps-Sets the 
speed format to frames per 
second (fps). 


Video off-Turns the video 
output off . 


Video on-Turns the video 
Output On. 


This command supports two item 
types: command and device 
specific. Common items include: 
length, mode, position, ready, 
time format, and volume. Device- 
specific items include: current track, 
length track number, number of 
tracks, position in track, position 
position track number, and speed 
format. The mode information 
includes: not ready, stopped, 
playing, seeking, recording, 
paused, or other. The volume 
setting returns the current volume 
as a string /e/i:right. Each value 
is a percentage of the total volume. 


Description 


This command returns the specified 
device status information. 


These are no items associated with This command stops the device. 
this command. 


As you can see, the table contains fairly straightforward 
commands. You might not find some of them on your remote 
control at home, but they are essential to computer use of these 
devices. These additional commands are what make automatic 
device control using the computer possible. They also provide 
the level of flexibility required to create fully functional 
applications using REXX (the topic of the next section). 


Using MC[ with REXX 


Some people might find it amusing to think that you could create a fully 
functional multimedia application with what amounts to a glorified 
batch language. Yet, REXX is a lot more than simply a batch language. 
Chapter 1 provides you with a full view of this rather flexible batch 
language. There is even talk of creating a REXX compiler (much like 
the batch file compilers used with DOS). 


The important point to remember is that you can create a REXX 
multimedia application and not worry if the host machine contains a 
full multimedia suite. You can determine what capabilities the 
machine provides and program around any problem areas. You could 
do this with a standard language like C as well. The advantage to 
using REXX is that you need nothing more than a standard OS/2 
installation. 


Unfortunately, there are a few limitations to using REXX as your 
multimedia programming language. In most cases, you probably will 
find these limitations of little consequence unless you plan to create 
an application for musicians or other multimedia professionals. If 
your only goal is to create an application that plays existing files or 
perhaps interacts with a few common devices, REXX probably 
provides everything that you need. The following paragraphs outline 
the limitations of using REXX as a multimedia programming 
platform: 


> MMPM/2 does not notify your REXX application when it loses 


or gains access to an MCI device, which means that you should 
open these devices exclusively. This prevents sharing by other 
applications and inconveniences the user a little. 


> If you do decide to share the device with other applications, 


then place an Acquire Exclusive/Release Return command 
sequence around each of your MCI commands. This prevents 
another application from using the device while your 
application is using it. This also means that you must add error 
trapping because the Acquire Exclusive command will fail if 
another application is using the device. 
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> Opening a device in exclusive mode becomes a greater 


inconvenience if you hold it open for a long time. Make 
sure you release device control whenever possible to give 
other applications an opportunity to use the device. 


> Try to create PMREXX applications instead of REXX 


applications. Many MCI commands require PM to work. For 
example, video image device and cut and paste commands 
fall into this category. 


> The wait flag is the only way to maintain program 


synchronization. It is a lot less efficient than many of the 
methods available using standard languages. 


> Using asynchronous device access requires additional 


programming on your part. REXX does not receive PM 
messages. This means that your application will not receive 
notification when a file or other media stops playing. Use 
the Status Mode command and a polling loop to get around 
this limitation. 


> MCI does perform implicit opens. This means that you can 


play a file without opening a device. The only down side to 
this arrangement is that an implicit open always opens the 
device in shareable mode. This means that another 
application could interrupt you in the middle of playing a 
file. 


As you can see, programming a multimedia application in REXX is 
no picnic, but you can do it. There is one more area that you need 
to learn about to complete the picture. MCI also includes several 
functions that provide the actual interface between REXX and 
MMPM/2. Remember, the previous section described commands. 
The commands are the MMPM/2 part of the picture. Table 7-2 
provides a list of REXX functions that you use to work with MMPM/2. 


REXX MCI functions 


Function D es cription 


CALL mcipxlnit 


CALL mciF3xExit 


This function initializes the MCI string interface to REXX. It does not 
require any parameters. It does return 0 for a successful completion. 
This function terminates a REXX file containing MCI string 
commands. It does not require any parameters. It returns 0 


Function 


ulDevlD = 
mciBXGetDevicelD 
(sAlias) 


rcl= 
mcipxGetErrorstring 
(rc2, `sErrorstr') 


rc= 
mciBxsendstring 
(`scmdstr', 
`sBetvalue', 
sBeserved l , 
sBeserved2) 


Description 


for successful completion. You must call this function to 
return allocated resources to the system. 


This function returns the device identifier associated with an MCI 
device alias. ulDevlD contains the same device identifier returned 
with the Open command. sAlias contains a string that identifies the 
device specified using a previous Open command. 


This function returns the MCI error string that matches the specified 
error code. rcl contains 0 for successful completion or an error 
code. rc2 contains the MCI return code. sErrorstr contains the error 
string. Notice that it appears within single quotes. 


This function sends an MCI command string. See Table 7-1 for a 
complete list of these commands. rc contains 0 for successful 
completion or an error code. scmdstr contains the MCI command 
string within single quotes. sBetvalue contains the return value of 
the MCI command string. sBeservedl and sBeserved2 are 
reserved parameters; set them to 0. 


As you can see from the table, five simple commands are all you need 
to create a multimedia program using the commands in Table 7-1. 
There is one final REXX-specific reminder about the functions listed 
in Table 7-2: remember that you must register the mciRxlnit function 
before you use it. Once you perform this task, you can use any other 
MCI REXX function or command string (listed in Table 7-1). 


Now that you understand the basics, lets look at some actual 
example code. Figure 7-1 provides an example of how you can 
create a PMREXX application that uses a variety of multimedia 
devices to play files or other media. It also demonstrates one 
method that you can use for retrieving the installed base of 
multimedia devices on the host machine. Figure 7-2 shows the 
display provided by this application. 


REXX MCI string programming demonstration source code. 


/* BEXX MCI String Programming Demonstration 


This program demonstrates some of the tasks you can perform using the 
multimedia capabilities provided with the Mcl string capabilities provided 
for BEXX. To use this application, you require the following equipment: 
any sound board, a CD-BOM drive, and any other multimedia devices you 
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wish to test. 
This is a PMF3EXX application. Simply type PMF3EXX PRGO8-01 at the 
OS/2 command line to run it. You can also add it to the desktop using 
tch8ppyrr9gghrtaTgtge3m_Pj8thehMueHerandTabBooks 


*/ 


/* lnitialize the Mcl string interface. */ 


CALL BXFUNCADD "mciBxlnit", "MCIApl", "mciBxlnit" 
CALL mciBxlnit 


/* lnitialize the BEXX utility functions. */ 


CALL BXFUNCADD "SysLoadFuncs", "Bexxutil", "SysLoadFuncs" 
CALL SysLoadFuncs 


/* Display the capabilities of this machine. */ 


CALL proddisp 


/* lf the user's machine has a wave audio device, ask if they want to play a file */ 


CALL waveplay 


/* Exit the routine */ 


CALL mciRXExit 


EXIT 


proddisp: PBOCEDUBE 


/* This procedure displays the capabilities of this machine by first 


checking to see if the device exists, then using the Capability command 
to display its capabilities. 


*/ 


/* This section checks for video tape, then displays its capabilities. */ 


rc = mciF]xsendstring(`lNFO video tape product', `sprodstr', `0', `0') 
lF rc = 0 THEN SAY `Video Tape -' sprodstr; ELSE SAY `No Video Tape lnstalled' 
rc = mciBxsendstring(`OPEN video tape alias checkdevice', `sNullstr', `0', `0') 
lF rc = 0 THEN CALL dispdevcap 
rc = mciRxsendstring(`CLOSE checkdevice', `sNullstr', `0', `0') 
SAY 


/* This section checks for video disk, the displays its capabilities. */ 


rc = mciRxsendstring(`lNFO video disk product', `sprodstr', `0', `0') 
lF rc = 0 THEN SAY 'Video Disk -' sprodstr; ELSE SAY `No Video Disk lnstalled' 
rc = mciBxsendstring(`OPEN video disk alias checkdevice', `sNullstr', `0', `0') 
lF rc = 0 THEN CALL dispdevcap 
rc = mciRxsendstring(`CLOSE checkdevice', `sNullstr', `0', `0') 
SAY 


/* This section checks for CD audio, the displays its capabilities. */ 


rc = mciBxsendstring(`lNFO cdaudio product', `sprodstr', `0', `0') 
lF rc = 0 THEN SAY `CD Audio -' sprodstr; ELSE SAY `No CD Audio lnstalled' 
rc = mciBxsendstring(`OPEN cdaudio alias checkdevice', `sNullstr', `0', `0') 
lF rc = 0 THEN CALL dispdevcap 
rc = mciF3xsendstring(`CLOSE checkdevice', `sNullstr', `0', `0') 
SAY 


/* This section checks for wave audio, then displays its capabilities. */ 


rc = mciF}xsendstring(`lNFO waveaudio product', `sprodstr', `0', `0') 
IF rc = 0 THEN SAY `Wave Audio -' sprodstr; ELSE SAY `No Wave Audio lnstalled' 
rc = mciBxsendstring(`OPEN waveaudio alias checkdevice', `sNullstr', `0', `0') 
IF rc = 0 THEN CALL dispdevcap 
rc = mciRxsendstring(`CLOSE checkdevice', `sNullstr', `0', `0') 
SAY 


/* This section checks for sequencer, then displays its capabilities. */ 


rc = mciBxsendstring(`lNFO sequencer product', `sprodstr', `0', `0') 
IF rc = 0 THEN SAY `Sequencer -I sprodstr; ELSE SAY `No Sequencer lnstalled' 
rc = mciBxsendstring(`OPEN sequencer alias checkdevice', `sNullstr', `0', `0') 
lF rc = 0 THEN CALL dispdevcap 
rc = mciRxsendstring(`CLOSE checkdevice', `sNullstr', `0', `0') 
SAY 


/* This section checks for digital video, the displays its capabilities. */ 


rc = mciBxsendstring(`lNFO digitalvideo product', `sprodstr', `0', `0') 
IF rc = 0 THEN SAY `Digital Video -' sprodstr; ELSE SAY `No Digital Video lnstalled' 
rc = mciBxsendstring(`OPEN digitalvideo alias checkdevice', `sNullstr', `0', `0') 
lF rc = 0 THEN CALL dispdevcap 
rc = mciF}xsendstring(`CLOSE checkdevice', `sNullstr', `0', `0') 
SAY 


/* Beturn to the calling procedure. */ 


RETUF3N 


dispdevcap: PF30CEDUF3E 


/* This procedure actually displays the wave audio information. */ 
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rc = mciBxsendstring(`CAPABILITY checkdevice can record WAIT', sprodcapl , 0, 0) 
SAY`Can Becord: `sprodcapl 
rc = mciBxsendstring(`CAPABILITY checkdevice has audio WAIT', sprodcap2, 0, 0) 
SAY `Has Audio: ` sprodcap2 
rc = mciBxsendstring(`CAPABILITY checkdevice has video WAIT', sprodcap3, 0, 0) 
SAY `Has video: ` sprodcap3 
rc = mciBxsendstring(`CAPABILITY checkdevice can eject WAIT', sprodcap4, 0, 0) 
SAY `Can Eject: ` sprodcap4 
rc = mciRxsendstring(`CAPABILITY checkdevice can play WAIT', sprodcap5, 0, 0) 
SAY `Can play: ` sprodcap5 
rc = mciBxsendstring(`CAPABILITY checkdevice can save WAIT', sprodcap6, 0, 0) 
SAY `Can save: ` sprodcap6 
rc = mciBxsendstring(`CAPABILITY checkdevice compound device WAIT', sprodcap7, 0, 0) 
SAY `Compound Device: ` sprodcap7 
rc = mciBxsendstring(`CAPABILITY checkdevice uses files WAIT', sprodcap8, 0, 0) 
SAY`UsesFiles: `sprodcap8 
rc = mciBxsendstring(`CAPABILITY checkdevice can lockeject WAIT', sprodcap9, 0, 0) 
SAY `Can Lockeject: ` sprodcap9 
rc = mciBxsendstring(`CAPABILITY checkdevice can setvolume WAIT', sprodcaplo, 0, 0) 
SAY `Can Set Volume: ` sprodcaplo 
rc = mciBxsendstring(`CAPABILITY checkdevice preroll type WAIT', sprodcapl 1, 0, 0) 
SAY `Preroll Type: ` sprodcapll 
rc = mciBxsendstring(`CAPABILITY checkdevice preroll time WAIT', sprodcapl2, 0, 0) 
SAY `Preroll Time: ` sprodcapl2 
rc = mciBxsendstring(`CAPABILITY checkdevice device type WAIT', sprodcapl3, 0, 0) 
SAY`DeviceType: ` sprodcapl3 


F3ETURN 


waveplay: PF{OCEDURE 


/* This procedure asks the user to enter the path and filename of a wave file. It 


then plays the file for the user. 


*/ 


/* Determine if device is available. */ 


rc = mciF3xsendstring(`lNFO waveaudio product', `sprodstr', `0', `0') 
lF rc 0 THEN RETUF3N 


/* Determine if user wants to play a file. */ 


SAY `Do you want to play a .WAV file? (YES or NO) ` 
PULL sAnswer 
lF sAnswer = `NO' THEN RETURN 


/* Get the filename and create a file load string. */ 
SAY `Enter the WAV path and filename: ` 
PULL sFileName 


sLoadstr = `LOAD waveaudio ` sFilename ` WAIT' 


/* Open the device, load the file, play the file, and close the device. */ 


rc = mciF3xsendstring(`OPEN waveaudio WAIT', `sDevlD', `0', `0') 
rc = mciRxsendstring(sLoadstr, `sNullstr', `0', `0') 
rc = mciBxsendstring(`PLAY waveaudio', `sNullstr', `0', `0') 
rc = mciRxsendstring(`CLOSE checkdevice', `sNullstr', `0', `0') 
Beturn 


As you can see from Fig. 7-1, the actual procedure for using MCI 
strings in an application is quite simple. In most cases, you 
use the mciRxsendstring function to output the commands 
required to make the application work. This is the technique 
used to obtain all the device specific information for the host 
machine. Notice that this application makes use of the alias 
capability provided by the REXX MCI string facility. This 
allows the application to use a single procedure to process 
each device, even though the devices normally use different 
names. The technique also allows the application to avoid 
using queues or other techniques to get the work 
accomplished. Using the alias capability can save you a lot of 
time and effort in creating your application. Avoid the pitfall 
of using an ambiguous name for the device alias. Notice that 
the name chosen in this case reflects the actual use of the 
alias within the application. 


There are a few other tricks in this application. Notice the last 
procedure in the application. It uses the user input to build a load 
string for the application. This load string allows you to load the 
requested file without really knowing what it is in advance. You would 
need to add some error trapping to an actual application, but this 
sample shows you how to get started. Remember that you must pass 
strings in the mciRxsendstring function; variables are either 
misinterpreted or result in an error. This means that you must always 
create a string before calling the function. 


Figure 7-2 shows that the output from this application is fairly simple, 
but it does provide a lot of useful information. You normally would use 
this information to determine the host machine capabilities before you 
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Compound Device TRUE 
Uses Flies. TRUE 
Can I,ocke].ect : FAI.SE 
Can Set Volume TRUE 
Prerc)ll Ty|Je. 3 
Prerc]ll Time: 0 
Device Type : DigitalvidecJ 


Dc] yc]u want tc] play a WAV I ile? {YES or NO) YES 


Enter the WAV path and I ilename: D.\WIN`COOI(OO WAV 


REXX MCI string programming demonstration output 
display. 


attempted to perform some task. Using PMREXX allows you to create 
a better-looking display and perform a few additional tricks with 
your MCI applications. Always refer to the REXX limitations in the 
previous paragraphs before you commit to a REXX-specific 
application. Most MCI capabilities run better under PMREXX. 


Understanding the 
U]timedia Toolkit 


The Ultimedia Toolkit is more than just another library, drawing tool, 
or utility application. It is a CD filled with many of the tools required 
to build a fully functional multimedia operating environment. This 
includes some of the more mundane activities like drawing graphics as 
well as some of the more exciting tasks like creating your own video. 
You don't have to be a programmer or a graphics artist to appreciate 
this toolkit (of course, it helps). These tools provide a lot of power 
without a lot of complexity. 


From a programmer's perspective, the Ultimedia Toolkit provides 
some tools that you might never use. For example, few programmers 
will need the video capabilities of the product (at least in today's 
programming environment). On the other hand, all the viewers 
provided with this product allow you to build REXX or C applications 
that display information with a minimum of fuss. For instance, you 
could use the image viewer to display a BMP file while getting your 
REXX application initialized. Perfect Image/2 allows you to create 
detailed BMP and other video aids without resorting to the clunky 
editors many programmers try to use. You could even use the AVA/2 
scripting language provided with Builder/2 to create a multimedia 
application without resorting to other programming languages. The 
AVA/2 scripting language provides the hooks you need to access 
your C applications or DLLs; allowing you to expand the capabilities 
of this product. 


The Ultimedia Toolkit contains three components: Builder/2, Perfect 
Image/2, and Workplace/2. IBM also sells these three tools 
individually. Each product addresses a different need, so you can buy 
what you need without paying for what you don't want. The following 
paragraphs describe each tool in detail. You'll want to actually use 
them to see their full potential. 


Builder/2 


Builder/2 really is several tools in one. All the tools work together to 
create a fully functional multimedia author environment. This makes 
Builder/2 different from many of the products currently on the market. 
You actually can use this product to build applications, other products 
stop far short of this goal. Builder/2 contains the following elements: 


> Scripting language and runtime environment to play the scripts. 


> Interactive tool you can use to create scripts. 


> Text/hex editor. 
> Image, video, audio, and story browsing tools. 


Each of these tools perform a different function. The AVA/2 scripting 
language helps you create multimedia programs. Like all programs, they 
consist of a set of computer instructions in human readable format. Unlike 
most programming languages, this one is specially designed for multimedia 
applications. You can easily expand this capability using C applications and 
DLLs. 


Building a multimedia application requires you to use video and audio files. 
You can select from a variety of sources using Builder/2. The following list 
shows the graphics, video, and audio formats supported by this 
environment : 


> AVC digital audio (AD, AU) (The Audio Visual Connection) 


> AVC digital image (IM) (The Audio Visual Connection) 
>DVI 


> M-Motion Video (MOT) 


> MIDI (MID) 


5> OS/21.3 and 2.x bitmaps (BMP) 
>PCX 


> Targa (TGA) 


> TIF (Intel and Motorola) 


> Wave (INAV) 


> Windows 3.x bitmaps (BMP) 


Builder/2 provides a wide variety of other items as well. For example, it 
provides a complete tutorial that you can use to learn the product. In addition, 
the menu-driven application builder allows you to create a multimedia 
presentation without knowing how to use the AVA/2 language. Figure 7-3 
shows a picture of this front end. Notice that it provides boxes where you 
place the various elements of your presentation. While this interface will not 
allow you to fully utilize the power of Builder/2, it does make it a lot easier to 
learn the product. Contrast this with the text (command interface) shown in 
Fig. 7-4. 


Ultimedia Builder/2 main window graphic display. 


Ultimedia Builder/2 main u)indow text display. 


Figure 7-3 
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Builder/2 also provides five very useful utility programs. The main 
purpose for these utilities is to help you find the files that you need to 
create multimedia programs quickly and efficiently. None of the 
utilities are particularly exciting when you look at them individually. 
However, you probably will find them indispensable because of their 
quick load times. These utilities help you find what you need in the 
smallest amount of time possible. 


The Text/Hex Browser doesn't do anything very special; it doesn't 
even provide any editing controls that you can use to modify a file. It 
does provide an easy way of checking a graphics file for damage or 
reading a text file. Theoretically, you could use it for a variety of 
purposes. Under DOS, the small memory footprint of this utility 
would provide a real reason to use it, but this isn't a very big problem 
under OS/2. Figure 7-5 shows the Text/Hex Browser. As you can 
see, it is very simple in design. Most programmers probably have 
something better in their arsenal, but this application could help 
when you least expect it. 
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The Text/Hex Browser does provide two extremely useful features 
that you might or might not have in your current viewer. First, 
nonprintable characters appear as their ASCII graphic equivalent. 
This can help you see file patterns that you could easily miss 
otherwise. It could help you locate extended ASCII characters as well. 
Second, the editor includes a search facility. This allows you to find 
what you need in the file quickly. Unfortunately, attempts to enter 
hexadecimal values didn't succeed. The search capability extends to 
ASCII characters only. 


The Image Browser tool provides a simple way to quickly look at 
drawings or images. It supports all the file formats supported by 
Builder/2 so that you could use it as a means of performing a 
preliminary scan of your graphics files. You also could use it as the 
default viewing device for specific file extensions. One of the nice 
features of this little utility is that you can resize the image by simply 
moving the frame. Image Browser provides a display of the amount of 
expansion or compression as a percentage on the title bar. Figure 7-6 
shows a typical Image Browser display. Notice there are no real 
controls or menus except those provided to every OS/2 application. 


Ultimedia Image Browser. 


The Video Browser allows you to look at AVS or DVI video files. It 
simply plays the contents of the file for you. There are no editing 
tools provided with this utility. 


The Audio Browser looks like many of the WAV file players provided 
with various sound board products and with OS/2. There is one 


unusual feature provided with this utility, you can use the two sliders 
to select the start and end time of the audio playback. This allows you 
to determine where you need to cut a large audio file to get the part 
that you need for your presentation. Figure 7-7 shows a typical Audio 
Browser dialog box. Notice that this utility does not provide any 
menus or other controls. This makes it perfect as an adjunct to a 
REXX application. You can simply call it from the command line with 
the name of the file that you want to play. 
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Figure 7-8 
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The final utility provided with Builder/2 is the Story Browser. This 
utility provides quick text view of the commands in a Builder/2 file. 
Instead of waiting for the entire application to start, you can get an 
immediate view of a file using this utility. As with the Text/Hex 
Browser, this utility does not provide any editing controls; it simply 
lets you view the story file contents. It also provides the same search 
capability as the Text/Hex Browser. Figure 7-8 shows a typical Story 
Browser display. 
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Perfect Image/2 


Perfect Image/2 is an image-processing tool. This is different from a 
drawing tool in that Perfect Image/2 doesn't include any drawing 
tools. It simply processes graphics that you already have or accepts 
input from an input device like a video camera. It modifies these 
images much like you would by adding lenses or filters to a camera. 
The best part of this is that you can obtain very precise effects that 
you could not obtain using a camera. The following list tells you 
about the capabilities of Perfect Image/2: 


> Displays a wide variety of image formats. This allows you to 


search for specific images. Perfect Image/2 provides better 
image display capabilities than the Image Browser provided 
with Builder/2. 


> Converts a subset of the image formats it displays. This allows 


you to transfer images from one application to the next. You 
also can use it to convert the image to a format that works 
better with specific applications. (In some cases, using a 
different format actually can enhance an image's appearance 
due to the method the application uses to process it.) 


> Adjusts, balances, and filters image colors. This is the same 


effect as adding a filter to your camera. This big difference is 
that you can do it with images other than the ones you retrieve 
from an input device. In addition, the effects that you achieve 
are much more precise than those you can obtain from a 
camera lens. 


> Copy and paste images between applications or parts of 


images between screen locations. The big difference between 
this copy and paste and that provided by other applications is 
the types of things you can do to the image. This includes: 
copy and paste irregular images, fuzzy edge images, control 
transparency images, flip and rotate images, resize the image, 
and blend the image. All these processes allow you to modify 
the image's appearance without using drawing tools. This does 
not actually allow you to create a new image like a drawing 
tool would. 


> Capture video images if you have a capture adapter. This allows 


you to create onscreen presentations using the same props that 
you would use for a person-to-person presentation. The big 
difference is that you can send this presentation to as many 
people as necessary by including a disk with your package. 


> Display and modify TIE FAX image objects. This assumes that 


you have a FAX board in your machine and that the software 
recognizes the board. You could use this capability to enhance a 
FAX before sending it to upper management. 


> Print the images that you display. This allows you to create a 


hardcopy for mailing or future reference. The print capability is 
not much better than the standard OS/2 print capability. 
However, this product does provide various printing levels that 
can greatly enhance image output, especially on a color printer. 


> Limited editing features. There are no drawing features 


provided with Perfect Image/2, but you can increase or 
decrease image size, crop the image borders, and flip it 
horizontally or vertically. These transform functions can help 
you manipulate the image a little but really don't fall within the 
realm of image drawing. This only serves to point out the 
modification nature of Perfect Image/2. 


Perfect Image/2 can retrieve and display a wide variety of graphic 
images. Even though there are many products on the market that can 
work with a wider variety of images, most of them are either data 
conversion or drawing programs. Remember that Perfect Image/2 is 
an image processor. This means that you can import an image, 
process it using various filters and effects, and export it to another 
application. The following list shows the graphic image formats this 
product supports: 


> AVC (AD, AU, and IM) (The Audio Visual Connection) 


> OS/21.3 and 2.x bitmaps (BMP) 


5> PCX 


> Targa (TGA) 


> TIF (Intel and Motorola) 


> TIFF (single-bit FAX file) 


> Windows 3.x bitmaps (BMP) 


Many of these image formats support more than one bit-count range. 
(The bit count determines how many colors the file can contain.) 
Perfect Image/2 supports the following bit counts: 1-bit (FAX 
format), 8-bit (256 colors), 16-bit RGB (64K colors), and 24-bit RGB 
(16.7M colors). Notice that it does not support 16-color input. Use a 
draw program like Paintbrush to convert the image from 16 colors to 
256 colors. All of these bit counts correspond to the counts 
supported by most display and color printer devices. 


Perfect Image/2 provides an easy-to-use graphic interface and 
toolbar. Figure 7-9 shows a typical Perfect Image/2 display. The File 
menu contains the usual entries for opening and closing files. It also 
contains two levels of image printing. One of the more interesting 
options is Properties. This option displays a dialog box containing 
the image parameters including: format, bit count, date and time 
stamp, size, and on-disk storage requirements. 


Ultimedia Perfect Imagal2 Main Window. 


The Edit menu contains the normal copy, paste, and undo entries. It 
also allows you to size, crop, and flip the image. The Select menu 
allows you to select the entire or specific parts of the image as well as 


rotate it and perform other types of transforms. The View menu 
allows you to determine the quality of the display, amount of zoom, 
and whether Perfect Image/2 displays various masking elements. This 
Video display works with a video camera. It allows you to look at a 
live display, capture the current image, and select the video capture 
parameters. The Enhance menu contains all sorts of options that you 
can use to modify the appearance of a picture. This includes several 
types of filters, color adjustments, and blending. The Options menu 
helps you adjust Perfect Image/2 for optimal picture display. It 
includes options like the fuzz width used for blending and other 
modifications and the amount of picture transparency. The Windows 
and Help menus perform the same tasks that they do in most 
applications. 


Figure 7-10 shows the toolbar that normally appears at the left side 
of the display. This provides the tools that you need to modify an 
image including: Select, Lasso, Node, Botate, Mask area, Unmask 
area, Draw mask on, Draw mask off, Clear mask, Automask, Tool 
size, Blend, Adjust colors, Color balance, Copy, Paste, Zoom in, 
and Zoom out. Most of the tools are pretty self explanatory. 


Ultimedia Perfect Imagal2 tool bar 
with callouts. 


Of special interest are the Select, Lasso, Node, and Botate options. 
These four options allow you to perform specific transforms visually 
instead of relying on menu options. The various mask options allow 
you to apply filters to the image. The Color options determine how 
the masks affect the appearance of the image. The Zoom options 


affect your perception of the image but do not affect the image itself . 
Finally, the Copy and Paste options work with the Select option to 
copy and paste all or part of the image. As you can see, Perfect 
Image/2 excels at image manipulation. 


Workplace/2 


Workplace/2 is an organization tool. If you have ever worked on a large 
programming project with a lot of icons, then you can appreciate the 
need for organization. Team projects require this organization even 
more. Ever try to get someone up to speed after the project gets 
started? It takes a lot of time and effort to do this-time that you could 
spend writing the application. Some people might view Workplace/2 as 
the graphic artist's or presentation expert's dream, but programmers 
can use it to organize their graphic files as well. 


There are two unique tools provided with Workplace/2. These tools 
aren't tools in the normal sense of the word, they simply look like file 
folders. The installation program adds them to your Templates folder. 
Workplace/2 also contains the five browsers described in the 
Builder/2 section along with these unique tools. 


The first folder is Light Table. The magic of this product lies in what 
the folder does for you. Instead of displaying the standard icon, these 
folders display the actual contents of the graphics files. Instead of 
having to guess what HAND.PCX contains, you could simply look at 
the file icon and see what it contains. Figure 7-11 shows a typical 
Light Table file. 
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Figure 7-11 


Notice that each file icon (except the story file) contains a thumbnail 
sketch of its contents. The story file is an exception. Because this file 
contains a multimedia application, it contains the Story Browser icon. 
The same is true for audio and video files. They use a default icon 
instead of something unique. Double clicking on the file brings up one 
of the browsers discussed in the Builder/2 section of the chapter 
(unless you purposely associate the file with another application). In 
most cases, a browser will act a lot quicker and provide all the 
information that you need to know about the file until you actually 
use it. The counterpoint to this is that you might want to use it 
immediately instead of waiting until later. 
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format before Workplace/2 will display the contents of these files in a 
Light Table file. The same applies to many other graphic formats. If 
you experience difficulty getting the Light Table to read the file, then 
try installing support for it. 


Opening the settings for a Light Table entry reveals another 
difference between it and a standard graphics file entry. There is a 
Reference page to the Notepad. Figure 7-12 shows a typical 
Reference page. Notice that this page contains the actual filename, a 
reference number, and a few other entries. The important entry is the 
Subject field. This is the entry that you use to help define the file. 
This information helps you locate the file later. In essence, it allows 
you to perform a database type search through your graphic files. 
What this means is that, if you need a hand icon, you can either 
search through your files one at a time or use the Workplace/2 query 
capability to find it almost instantly. 


The database capability of Workplace/2 doesn't end here. You can 
specify additional data items by changing the Schema page of the 
Light Table folder's notebook. You can store the information in the 
file's EAs or in an external database. If you choose an external 
database, then the Light Table folder creates a link with an SQL 
database that stores the extra Reference page entries. (Workplace/2 
can access dBASE IV, OS/2 Database Manager, or Oracle files.) 
Either choice allows you to create as many fields as you require to 
define a multimedia file. This flexibility means that you potentially 


Multimedia File Reference 
dialog. 


could create a database of enormous size. Some prior planning will 
help you keep the number of fields to a minimum. Remember that 
too much information is almost as bad as too little. 


Select ``Extended Attributes" in the Extended Attributes field of the 
Schema page of the Light Table notebook if you do not want to 
create a separate database to hold your search information. This 
highlights the EA Edit button that allows you to create new fields for 
your multimedia file Reference page. This also allows you to perform 
a Light Table Folder query without resorting to using a database 
manager to store your search data. 


Whatever storage technique you choose, there are three steps in 
defining the schema of your multimedia storage. Figure 7-13 shows 
the three steps. The first step is to get the Schema page (upper left 
dialog box). The second step is to add one or more fields. You do this 
by selecting the Add button of the Schema Editor dialog box (upper 
right dialog box). Two other buttons allow you to delete or modify the 
entries that you create. The final step is adding the actual entry. This 
consists of filling out four fields. The Name field determines what you 
call the entry in queries. The Type field determines the type of 
information that this entry will contain. For example, a title would 
contain character information, while a job number would contain 
numeric information. The Size field determines how large the field is. 
You need to exercise some care with this entry because even a few 
characters or numbers can make a big difference in the size of the 


Figure 7-12 


Figure 7-13 


Light Table schema and associated dialogs. 


EAs or database. Numeric information can contain integers as well as 
decimals. Simply separate the two entries by a comma. For example, 
4,2 would create a numeric entry four characters long, two of which 
are decimals. The Media Reference entry determines if this is a media 
file link. You probably will set this entry to No more often than not. 


Creating a query requires several steps, even if you simply want to 
scan the multimedia file EAs. It also requires some knowledge of SQL. 
The Workplace/2 documentation does contain some basic pointers, 
but it is far from complete. Learning SQL is a small price to pay for 
the flexibility that this system provides. The first step is to create 
another Query Sequence file. Once you accomplish this task, create 
one or more LT Query entries in the folder. You also need to create 
an LT Query Result entry. Figure 7-14 shows a typical single query 
folder. 


Now that you have everything set up, it's time to enter all this 
additional information that you want to use for queries later. Open 
the Light Table folder that you plan to use for storage to the details 
view. You will see the standard entries when the view first opens. This 
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includes items like the file size and the creation date. Scroll past this 
information, and you'll see the fields that you entered in the Schema 
page. There is one entry in the details page for each file that you add 
to it. All you need to do is point with the mouse to where the field 
and the file intersect. Press Alt and mouse button 1 at the same time. 
This will open the entry for editing. The Details view looks similar to 
the one shown in Fig. 7-15. 
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Once you finish entering all the data, you can start to perform 
queries on your multimedia files. Double click on the Query entry of 
the Query Sequence folder. The first dialog box that you see allows 
you to select a database type or the Light Table folder. The source 
that you choose depends on how you set up your schema. The query 
and the schema must match. It helps to keep the schema page of the 
Light Table folder open as you create the query. 


Once you define a data source, you see the dialog box shown in Fig. 
7-16. This is where your knowledge of SQL gets tested. Figure 7-16 
shows the most common scenario. The SQL statement consists of 
three entries. The SELECT statement determines which fields the 
query displays. The FROM entry is important if you use a database to 
store the multimedia information. Simply type the location of the 
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database file on disk. Make sure that you include a path and drive. If 
you use EAs to store your data, then put a dummy entry here. 
Workplace/2 automatically replaces this value with the optional 
Folder field shown at the top of the dialog box. The WHERE 
statement tells what search criteria you want to use. In this case, the 
query looks for all multimedia files associated with project number 61 
and displays the BOOK_NAME and SUBJECT fields of the matching 
entries. 


Once you complete the query, select OK to close the dialog box. This 
saves the query. Workplace/2 allows you to create multiple Query 
entries. The position of these entries within the Query Sequence 
folder is very important. Workplace/2 operates on each query in turn 
and uses the result of that query as the source of information for the 
next query. Using multiple queries allows you to modularize your 
search criteria, making it much more likely that you can use the 
individual queries later by recombining them. Of course, this is just an 
overview of the whole process. 


There are three query specific options in the System menu of the 
Query Sequence folder. Bun Query performs the SQL instructions in 
your Query entries and displays the result in the Query Result entry. 
You can use the Check Query option to check your SQL statements 
for errors before you attempt to run them. This is a very important 


Figure 7-16 


step, especially when you start learning to use Workplace/2. The 
Cancel Query option allows you to stop a long query before it 
completes. This is a handy option if you have a lot of data to search 
and think that one of the queries failed. It also allows you to get out 
of a query and quickly change the parameters. 


Figure 7-17 shows the final result of using the query mechanism 
provided with Workplace/2. As you can see, it provides all the 
information that you requested in an easy to read format. The dialog 
box also allows you to save the query results for future use or change 
the results into a new Light Table that you can use to store the 
resulting multimedia files. There are other options that allow you to 
change the appearance of the display. For example, you can change 
the size of the icons to small or medium (the default size is large). 
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As you can see, Workplace/2 is an extremely useful tool for 
managing your multimedia files. It doesn't matter if you're a graphic 
artist or a programmer, the needs are the same. The only real 
difference is the criteria used to search for these files. Workplace/2 
provides more than sufficient flexibility to allow you to modify the 
storage and query criteria to meet your needs. 
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VEN though memory prices consistently decrease (despite a 
few ups and clowns from time to time), no programmer can 


say that it's a quantity to waste on any machine. Few applications on 
the market today can say that they have sufficient memory to 
perform every task the user requires without also incorporating some 
form of memory management. (The only exception is utility 
applications that usually fall into this category anyway.) Whether 
memory management includes the dynamic allocation of variables or 
not is immaterial; there are many other forms of memory 
management that programmers might not even recognize as such. 
Any application that performs a significant amount of work will need 
memory management to get it done. This is old news to anyone who 
programmed in DOS. However, programming under OS/2 brings 
the programmer a new set of solutions and problems. 


Even OS/2 participates in this very necessary activity. As previously 
stated, memory management includes a lot more than simply 
obtaining and freeing pieces of memory. It also includes a wide 
variety of alternatives. For example, your application could use 
virtual memory to extend its resources instead of obtaining and 
freeing memory. Assuming the user does not run out of hard disk 
space, you could easily double or triple available memory with little 
additional programming. Unfortunately, that memory increase 
involves a very real speed penalty. As you can see, memory 
management is not an easy issue to deal with. 


This chapter takes a very low-level look at OS/2 memory 
management. It provides you with all the pieces required to create 
your own memory-management capabilities. Anyone creating an 
OS/2 program could benefit from the material in this chapter. It 
covers memory allocation, protection, virtual memory, and 
segmentation types. The chapter assumes that you want to create a 
general application-either character-mode OS/2 or something for 
the workplace shell. Even device driver and DLL writers need this 
type of information. 


DOS functions 


Memory management begins with the functions that you use to 
control it. OS/2 provides many different functions that you can use 
to obtain, free, share, and otherwise manage the memory used by 
your application. The following sections provide you with the detailed 
information required to use these functions. Each description consists 
of the function, its calling syntax, a listing of any errors it returns, 
and any other information you need to use it. 


DOSAIlocMem 


The DOSAllocMem function allocates private memory within the 
virtual address space. You can either reserve the memory or reserve 
and commit it. OS/2 allocates the memory from the process' private 
memory in multiples of 4K. Memory allocated and/or committed by 
this function is swappable to disk. You can apply any required 
protection to committed pages. OS/2 initially uses demand pages to 
fulfill the memory allocation requirements. You cannot access 
uncommitted pages. Execute and read accesses are the same when 
using an 80386 processor. This function uses the following syntax: 


rc = DOSAllocMem (pBaseAddress, ulobjectsize, ulAllocationFlags) 


The function provides only one return value (it does provide some 
return parameters discussed in the following paragraphs). rc contains 
a return code that tells you if the function completed without error. It 
also contains an error code if it didn't. Table 8-1 provides a list of 
these error codes. 


DOSAllocMem function return codes 


er 
Description 


NO ERROR 


ERROR NOT ENOUGH MEMORY 


ERROR INVALID PARAMETER 


ERROR INTERRUPT 


There are three parameters for this function. pBaseAddress 
contains the base address of the allocated private memory object. 
ulobjectsize contains the size of the memory object that you want to 
create. OS/2 rounds this value up to the nearest 4K (page size 
boundary). ulAIIocationFlags defines the allocation attributes and the 
access protection of the private memory object. You must set one of 
the following flags: PAG_READ, PAG_WRITE, or PAG_EXECUTE. 
All other flags are optional; set any unused bits to 0. 


The allocation attributes include: FAG COMMIT and OBJ TILE. Use 
the PAG_COMMIT flag to automatically commit all pages Tn the 
allocated private memory. Use the OBJ_TILE flag if you need to 
allocate the memory within the first 512MB of virtual address space 
so that you can use 16-bit alias selectors to map the memory object. 


The desired memory protection flags include: PAG_EXECUTE, 
PAG_READ, PAG_WRITE, and PAG_GUARD. The PAG_EXECUTE 
flag allows execute (essentially read) access to the private memory 
object. The PAG_READ flag allows the application to read the memory, 
but not write to it. The PAG_WRITE flag allows you to read and write 
the memory. The PAG_GUARD flag raises a ``guard page entered" 
condition each time the application tries to access the affected memory. 


DOSAllocsharedMem 


The DOSAllocsharedMem function allocates a shared memory object 
within the virtual address space. This function maps the virtual 
address space of the calling process to the shared memory object. 
OS/2 reserves the shared memory address in the same location for 
every process. Giving the shared memory object a name allows other 
processes to gain access to it using DOSGetNamedsharedMem. You 
must include the \SHAREMEM\ prefix to name the shared memory 
object. You cannot specify named shared memory as giveable or 
gettable. However, unnamed memory can receive these attributes. 
OS/2 always rounds the memory allocation request up to the nearest 
4K. OS/2 can move or swap committed memory. Execute and read 
accesses are equivalent when using an 80386 processor. This 
function uses the following syntax: 


rc = DOsphysicalDisk (pBaseAddress, pszName, ulobjectsize, ulFlags) 


Table 8-2 


The function provides only one return value (it does provide some 
return parameters .discussed in the following paragraphs). rc contains 
a return code that tells you if the function completed without error. It 
also contains an error code if it didn't. Table 8-2 provides a list of 
these error codes. 


DOSAllocsharedMem function return codes 


Error 


number Description 


0 NO ERROR 


8 ERROR NOT ENOUGH MEMORY 


87 ERROR INVALID PARAMETER 


95 ERROR INTERRUPT 


123 ERROR INVALID NAME 


183 ERROR ALREADY EXISTS 


There are four parameters for this function. pBaseAddress contains 
the base address of the allocated private memory object. pszName 
contains an optional ASCIIZ name for the shared memory object. 
Make sure you add the \SHAREMEM\ prefix to the name. 
ulobjectsize contains the size of the memory object that you want to 
create. OS/2 rounds this value up to the nearest 4K (page size 
boundary). ulAllocationFlags defines the allocation attributes and the 
access protection of the private memory object. You must set one of 
the following flags: PAG_READ, PAG_WRITE, or PAG_EXECUTE. 
All other flags are optional; set any unused bits to 0. 


The allocation attributes include: PAG_COMMIT, OBJ_GIVEABLE, 
OBJ_GETTABLE, and OBJ_TILE. Use the PAG_COMMIT flag to 
automatically commit all pages in the allocated private memory. The 
OBJ_GIVEABLE flag marks the memory segment as one that you can 
give to another process using the DOSGivesharedMem function. The 
OBJ_GETTABLE flag marks the memory segment as one that 
another process can access using the DOSGetsharedMem function. 
Use the OBJ_TILE flag if you need to allocate the memory within the 
first 512MB of virtual address space so that you can use 16-bit alias 
selectors to map the memory object. 


The desired memory protection flags include: PAG_EXECUTE, 
PAG_READ, PAG_WRITE, and PAG_GUARD. The PAG_EXECUTE 
flag allows execute (essentially read) access to the private memory 
object. The PAG_READ flag allows the application to read the 
memory, but not write to it. The PAG_WRITE flag allows you to read 
and write the memory. The PAG_GUARD flag raises a "guard page 
entered" condition each time the application tries to access the 
affected memory. 


DOSFreeMem 


The DOSFreeMem function reduces the object count of a private or 
shared memory object by one. It also frees the memory object from 
the virtual address space of the process. OS/2 gi.ves the released 
pages an access protection level of no access. The object does not 
get deleted until its object count is zero. More than one process can 
access the object; each access increments the object count. This 
function uses the following syntax: 


rc = DOSFreeMem (pBaseAddress) 


The function provides only one return value. rc contains a return 
code that tells you if the function completed without error. It also 
contains an error code if it didn't. Table 8-3 provides a list of these 
error codes. 


DOSFreeMem function return codes 
Table 8-3 


Error 
number Description 


0 NO ERROR 


5 ERROR ACCESS DENIED 


95 ERROR INTERRUPT 


487 ERROR INVALID ADDRESS 


There is one parameter for this function. pBaseAddress contains 
the base virtual address of the private or shared memory that you 
want to release. 


Table 8-4 


DOSGetNamedsharedMem 


The DOSGetNamedsharedMem function obtains access to a named 
shared memory object. This provides access to the object within the 
virtual address space of the calling process. You must include the 
\SHAREMEM\ prefix with the shared memory name. The 80386 
processor treats the execute and read access levels the same. Write 
access implies that you also gain read and execute access. The value 
of pBaseAddress returned by this function is the same value 
returned to the process that created the memory object. This function 
uses the following syntax: 


rc = DOSGetNamedsharedMem (pBaseAddress , pszsharedMemName, 
ulAttributeFlags ) 


The function provides only one return value (it does provide some 
return `parameters discussed in the following paragraphs). rc contains 
a return code that tells you if the function completed without error. It 
also contains an error code if it didn't. Table 8-4 provides a list of 
these error codes. 


DOSGetNamedsharedMem function return codes 


Error 


number Description 


0 NO ERROR 


2 ERROR FILE NOT FOUND 


8 ERROR NOT ENOUGH MEMORY 


87 ERROR INVALID PARAMETER 


95 ERROR INTERRUPT 


123 ERROR INVALID NAME 


212 ERROR LOCKED 


There are three parameters for this function. pBaseAddress 
contains the base address of the shared memory object on return. 
pszsharedMemName contains the name of the shared memory 
object. This is an ASCIIZ string in the form of an OS/2 filename. 


REgifeRE 


Remember to include the \SHAREMEM\ prefix. ulAttributeFlags 
contains the level of access protection that you want to set for the 
shared memory object. You must set one of the following flags: 
PAG_READ, PAG_WRITE, or PAG_EXECUTE. All other flags are 
optional; set any unused bits to 0. 


The shared memory object protection flags include: PAG_EXECUTE, 
PAG_READ, PAG_WRITE, and PAG_GUARD. The PAG_EXECUTE 
flag allows execute (essentially read) access to the private memory 
object. The PAG_READ flag allows the application to read the 
memory, but not write to it. The PAG_WRITE flag allows you to read 
and write the memory. The PAG_GUARD flag raises a ``guard page 
entered" condition each time the application tries to access the 
affected memory. 


OSGetsharedMem 


The DOSGetsharedMem function obtains access to an unnamed 
shared memory object. It provides access to the allocated memory in 
the virtual address space of the process. You must use the same base 
address as the process that created the gettable shared memory 
object. Using some format of interprocess communication (IPC) 
accomplishes this task. Both processes use the same base address to 
access the gettable shared memory object. The calling function must 
use the same access protection for committed pages as the process 
that originally created the shared memory object. The 80386 
processor treats the execute and read access levels the same. This 
function uses the following syntax: 


rc = DOSGetsharedMem (pBaseAddress, ulAttributeFlags) 


The function provides only one return value (it does provide some 
return parameters discussed in the following paragraphs). rc contains 
a return code that tells you if the function completed without error. It 
also contains an error code if it didn't. Table 8-5 provides a list of 
these error codes. 


Table 8-5 
DOSGetsharedMem function return codes 


Error 


number Description 


0 NO ERROR 


5 ERROR ACCESS DENIED 


8 ERROR NOT ENOUGH MEMORY 


87 ERROR INVALID PARAMETER 


95 ERROR INTERRUPT 


212 ERROR LOCKED 


There are two parameters for this function. pBaseAddress contains 
the base address of the shared memory object. This is the address 
returned by the DOSAllocsharedMem function to the creating 
process. ulAttributeFlags contains the level of access protection that 
you want to set for the shared memory object. You must set one of 
the following flags: PAG_READ, PAG_WRITE, or PAG_EXECUTE. 
All other flags are optional; set any unused bits to 0. 


The shared memory object protection flags include: PAG_EXECUTE, 
PAG_READ, PAG_WRITE, and PAG_GUARD. The PAG_EXECUTE 
flag allows execute (essentially read) access to the private memory 
object. The PAG_READ flag allows the application to read the 
memory, but not write to it. The PAG_WRITE flag allows you to read 
and write the memory. The PAG_GUARD flag raises a "guard page 
entered" condition each time the application tries to access the 
affected memory. 


DOSGivesharedMem 


The DOSGivesharedMem function gives another process access to a 
shared memory object. It provides access to the allocated memory in 
the virtual address space of the process (the same process performed 
by the DOSGetsharedMem function). Memory access uses the same 
base address as the process that created the giveable shared memory 
object. Use some format of interprocess communication (IPC) to 
exchange this information. The target function must use the same 


access protection for committed pages as the process that originally 
created the shared memory object. The 80386 processor treats the 
execute and read access levels the same. This function uses the 
following syntax: 


rc = DOSGivesharedMem (pBaseAddress idprocesslD, ulAttributeFlags) 


The function provides only one return value (it does provide some 
return parameters discussed in the following paragraphs). rc contains 
a return code that tells you if the function completed without error. It 
also contains an error code if it didn't. Table 8-6 provides a list of 
these error codes. 


DOSGivesharedMem function return codes 
Table 8-6 


Error 


number Description 


0 NO ERROR 


5 ERROR ACCESS DENIED 


8 ERROR NOT ENOUGH MEMORY 


87 ERROR INVALID PARAMETER 


95 ERROR INTERRUPT 


212 ERROR LOCKED 


303 ERROR INVALID PROCID 


487 ERROR INVALID ADDRESS 


There are three parameters for this function. pBaseAddress 
contains the base address of the shared memory object. This is the 
address returned by the DOSAllocsharedMem function to the 
creating process. idprocesslD contains the target process identifier. 
This is the process that receives shared memory access. 
ulAttributeFlags contains the level of access protection that you want 
to set for the shared memory object. You must set one of the 
following flags: PAG_READ, PAG_WRITE, or PAG_EXECUTE. All 
other flags are optional; set any unused bits to 0. 


The shared memory object protection flags include: PAG_EXECUTE, 
PAG_READ, PAG_WRITE, and PAG_GUARD. The PAG_EXECUTE 
flag allows execute (essentially read) access to the private memory 
object. The PAG_READ flag allows the application to read the memory, 
but not write to it. The PAG_WRITE flag allows you to read and write 
the memory. The PAG_GUARD flag raises a ``guard page entered" 
condition each time the application tries to access the affected memory. 


DOSQuervMem 


The DOSQueryMem function returns information about a range of 
pages within the virtual address space of the specified process. The 
information returned includes the type and access protection of the 
pages. You can provide an address range outside a previously allocated 
memory object (this is the only function that allows this practice). If your 
request extends outside the range of a single memory object, then 
DOSQueryMem returns an error code, the region attributes, length of 
the page range that matches the attributes of the first page in the 
region. Use the pulBegionsize parameter to determine the actual range 
of pages with matching attributes. You can use this value to determine 
the range of pages that the function did not scan. 


The function starts at the first page within the region and determines 
its state. It continues scanning pages until it scans the entire range, 
scans a page with a nonmatching attribute, or it encounters the first 
page of the next memory object (this allows you to determine the 
appearance of the virtual memory map including object boundaries). 
OS/2 considers a page region without the PAG_COMMIT or 
PAG_FREE allocation type as reserved; it has an access protection of 
no access. The 80386 processor treats the execute and read access 
levels the same. This function uses the following syntax: 


rc = DOSQueryMem (pBaseAddress, pulRegionsize, pulAllocationFlags) 


The function provides only one return value (it does provide some 
return parameters discussed in the following paragraphs). rc contains 
a return code that tells you if the function completed without error. It 
also contains an error code if it didn't. Table 8-7 provides a list of 
these error codes. 


DOSQueryMem function return codes 
Table 8-7 


Error 


number Description 


0 NO ERROR 


87 ERROR INVALID PARAMETER 


95 ERROR INTERRUPT 


487 ERROR INVALID ADDRESS 


There are three parameters for this function. pBaseAddress 
contains the base address of the memory object that you want to 
query. pulBegionsize contains the size in bytes of the range of 
pages that you want to query on entry. OS/2 automatically rounds 
this value to an even 4K page size. On return, this parameter 
points to a variable that contains the actual size of the range of 
pages in bytes. pulAttributeFlags contains: allocation type and 
access protection level. 


The allocation attributes include: PAG_COMMIT, PAG_FREE, 
PAG_SHARED, and PAG_BASE. The PAG_COMMIT flag indicates 
that OS/2 automatically commits all pages in the memory object 
region. The PAG_FREE flag indicates that the pages within the 
region are free. The PAG_SHARED flag indicates that pages are 
within a shared memory region. If this flag is not set, then the 
memory object exists within private memory. The PAG_BASE flag 
indicates the first page in an allocated memory object. 


The access protection level flags include: PAG_EXECUTE, 
PAG_READ, PAG_WRITE, and PAG_GUARD. The 
PAG_EXECUTE flag allows execute (essentially read) access to the 
private memory object. The PAG_READ flag allows the application 
to read the memory, but not write to it. The PAG_WRITE flag 
allows you to read and write the memory. The PAG_GUARD flag 
raises a "guard page entered" condition each time the application 
tries to access the affected memory. 


DOssetMem 


The DOssetMem function commits or decommits a range of pages 
within a shared or private memory object. You also can use it to alter 
their access protection or create a sparse collection of committed 
pages within a memory object. Every page within a memory object is 
free, private or shared. You cannot use this function to commit or 
decommit a free page. 


OS/2 allocates a committed page from backing storage (demand 
pages). Committing a reserved page within a shared memory object 
commits that page within each process that shares it. The first 
attempt to write to a committed page creates a page of zeros. You 
cannot decommit a committed page within shared memory. 
Decommitting a private page frees the backing storage and makes 
them inaccessible. OS/2 allows you to commit a decommitted page if 
there is sufficient backing storage. 


Setting the protection on a range of previously committed pages 
changes their access protection. You can set the access protection 
only of committed pages. The PAG_GUARD access protection 
attribute provides the means for automatic stack checking. (You also 
can use it to separate other data structures when necessary.) Each 
time a process attempts to access a range of guard pages, OS/2 
generates an access violation (page fault). This fault sets the access 
protection of the page and generates a condition that indicates a 
process entered the guard page. The 80386 processor treats the 
execute and read access levels the same. This function uses the 
following syntax: 


rc = DOssetMem (pBaseAddress, ulRegionsize, ulAttributeFlags) 


The function provides only one return value (it does provide some 
return parameters discussed in the following paragraphs). rc contains 
a return code that tells you if the function completed without error. It 
also contains an error code if it didn't. Table 8-8 provides a list of 
these error codes. 


DOssetMem function return codes 
Table 8-8 


Error 


number Description 


0 NO ERROR 


5 ERROR ACCESS DENIED 


8 ERROR NOT ENOUGH MEMORY 


87 ERROR INVALID PARAMETER 


95 ERROR INTERRUPT 


212 ERROR LOCKED 


487 ERROR INVALID ADDRESS 


32798 ERROR CROSSES OBJECT BOUNDARY 


There are three parameters for this function. pBaseAddress 
contains the base address of the memory object that you want to 
change. ulBegionsize contains the size in bytes of the range of 
pages that you want to change. OS/2 automatically rounds this value 
to an even 4K page size. ulAttributeFlags contains: commit type and 
access protection level. 


The allocation attributes include: PAG COMMIT and 
PAG_DECOMMIT. The PAG_COMMIT flag commits the specified 
range of pages in the memory object region. The PAG_DECOMMIT 
flag decommits the specified range of pages in the memory object. 
OS/2 will not change the commit type of the memory object unless 
you specify a commit type. 


The access protection level flags include: PAG_EXECUTE, 
PAG_READ, PAG_WRITE, PAG_GUARD, PAG_DEFAULT, and 
PAG_DECOMMIT. The PAG_EXECUTE flag allows execute 
(essentially read) access to the private memory object. The 
PAG_READ flag allows the application to read the memory, but 
not write to it. The PAG_WRITE flag allows you to read and write 
the memory. The PAG_GUARD flag raises a "guard page entered" 
condition each time the application tries to access the affected 
memory. The PAG_DEFAULT flag sets the access protection to the 
level specified by the initial process during allocation. The 


PAG_DECOMMIT flag decommits the specified memory object 
range. You must specify the PAG_READ, PAG_WRITE, or 
PAG_EXECUTE attributes if you do not set this bit. Set all other 
bits to 0. 


Table 8-9 


DOSsubAllocMem 


The DOSsubAllocMem function allocates a block of memory from a 
memory block previously initialized by the DOSsubsetMem function. 
OS/2 automatically rounds the allocation size up to the nearest 8 
byte multiple. The maximum value for ulsize is 64 bytes less than the 
memory pool size set by DOSsubsetMem. This function uses the 
following syntax: 


rc = DOSsubAllocMem (poffset, pBlockoffset, ulsize) 


The function provides only one return value (it does provide some 
return parameters discussed in the following paragraphs). rc contains 
a return code that tells you if the function completed without error. It 
also contains an error code if it didn't. Table 8-9 provides a list of 
these error codes. 


DOSsubAllocMem function return codes 


Error 


number Description 


0 NO ERROR 


87 ERROR INVALID PARAMETER 


311 ERROR DOSSUB NOMEM 


532 ERROR DOSSUB CORRUPTED 


There are three parameters for this function. poffset contains the 
memory pool offset that you want to use to allocate the block. 
pBlockoffset contains the DWORD address of the allocated memory 
block on return. ulsize contains the size of the requested memory 
block in bytes. 


DOSsubFreeMem 


The DOSsubFreeMem function frees a block of memory previously 
allocated using the DOSsubAlloc function. OS/2 automatically 
rounds the allocation size up to the nearest 8 byte multiple. The 
maximum value for ulsize is 64 bytes less than the memory pool size 
set by DOSsubsetMem. This function uses the following syntax: 


rc = DOSsubFreeMem (poffset, pBlockoffset, ulsize) 


The function provides only one return value (it does provide some 
return parameters discussed in the following paragraphs). rc contains 
a return code that tells you if the function completed without error. It 
also contains an error code if it didn't. Table 8-10 provides a list of 
these error codes. 


DOSsubFreeMem function return 
Table 8-10 


Error 


number Description 


0 NO ERROR 


87 ERROR INVALID PARAMETER 


312 ERROR DOSSUB OVERIAP 


532 ERROR DOSSUB CORRUPTED 


There are three parameters for this function. poffset contains the 
memory pool offset that you want to use to free the block. 
pBlockoffset contains the DWORD address of the allocated memory 
block. This is the same value returned by the DOSsubAllocMem 
function. ulsize contains the size of the memory block to free in 
bytes. 


DOSsubsetMem 


The DOSsubsetMem function initializes a memory that you can 
use for suballocation. You also can use this function to increase the 
size of a previously allocated pool. Use one of the other memory 


Table 8-11 


management functions to allocate a memory object before you call 
this function. Always call the DOSsubunsetMem function to return 
the memory resources to OS/2 before you exit the application. 
Otherwise, these resources remain unusable until the next system 
boot. 


There are a few other conditions that you must observe when using a 
memory pool. The minimum memory pool allocation is 72 bytes (64 
bytes for memory management and 8 bytes for one memory block). 
Never use the DOssetMem function on pages managed by a 
suballocation function. Every page spanned by the memory pool must 
have the same attributes to use suballocation management (read/write 
access is mandatory). This function uses the following syntax: 


rc = DOsphysicalDisk (poffset, ulFlags, ulsize) 


The function provides only one return value (it does provide some 
return parameters discussed in the following paragraphs). rc contains 
a return code that tells you if the function completed without error. It 
also contains an error code if it didn't. Table 8-11 provides a list of 
these error codes. 


DOSsubsetMem function return codes 


Error 


number Description 


0 NO ERROR 


87 ERROR INVALID PARAMETER 


310 ERROR DOSSUB SHRINK 


There are three parameters for this function. poffset contains the 
address of the memory pool that you want to use for suballocation. 
ulFlags describes the characteristics of the memory that you want 
to suballocate. ulsize contains the size of the memory pool in 
bytes. OS/2 automatically rounds this number to the nearest 
multiple of 8 bytes. 


The suballocation characteristic bits include: DOSSUB_INIT (0), 
DOSSUB_GROW (1), DOSSUB_SPARSE_OBJ (2), and 


DOSSUB_SERIALIZE (3). Set the DOSSUB_INIT flag to initialize the 
memory object for suballocation. Otherwise, OS/2 assumes that you 
want to attach a process to a previously initialized shared memory 
pool. Set the DOSSUB_GROW flag to increase the size of the 
memory pool. OS/2 ignores the DOSSUB_INIT flag if you set this 
flag. Set the DOSSUB_SPARSE_OBJ flag if you want a suballocation 
function to manage the commitment of pages spanned by the 
memory pool. Make sure there are no committed pages in the 
memory pool before using this flag. Always set this flag to its initial 
value before you issue a DOSsubsetMem grow request. Set the 
DOSSUB_SERIALIZE flag if you require serialized access to the 
memory pool. Always set this flag to its initial value before you issue 
a DOSsubsetMem grow request. 


DOSsubunsetMem 


The DOSsubunsetMem function ends the use of a memory pool. 
Using this function releases all resources used by the memory pool to 
general use. You must use this function before you free the memory 
object. This function uses the following syntax: 


rc = DOsphysicalDisk (poffset) 


The function provides only one return value. rc contains a return 
code that tells you if the function completed without error. It also 
contains an error code if it didn't. Table 8-12 provides a list of these 
error codes. 


DOSsubunsetMem function return codes 
Table 8-12 


Error 


number Description 


0 NO ERROR 


532 ERROR DOSSUB CORRUPTED 


There is one parameter for this function. poffset contains the 
memory pool offset. 


Memory protection 


There are several forms of protection provided with OS/2. Most of this 
protection is built into the processor itself . OS/2 merely makes use of 
these capabilities to provide a robust memory environment. It's the 
interaction of OS/2 with the processor that provides the protection your 
applications enjoy. Other forms of memory protection come as a result 
of the way OS/2 manages tasks and threads. The user does not have to 
worry about these protection schemes very much, but the programmer 
should at least know how they work. Unless you program in assembler, 
it is very unlikely that you will ever need to control the memory 
protection directly. The type of application that you create usually 
determines the required protection level and most C compilers have the 
required information built-in. 


One hardware-specific protection scheme used by OS/2 (and most 
advanced operating systems to varying degrees) is the layers of 
security built into the 80286 and above processors. Most of the lntel 
documentation refers to this protection as rings of security. The lower 
your access level, the more information you can access. Think of 
these rings of protection as the various levels of security implemented 
at any military base. Figure 8-1 provides you with a better idea of 
what these rings of security represent. 


We can extend our military analogy to the hardware security used by 
OS/2 even further. The outer ring (3) is unclassified. Any application 
can access this level of information. Every application must access this 
level to run at all. This level provides access to the resources that every 
application requires to function properly. However, at this level, 
resources are strictly controlled. For example, an application running at 
this level cannot access the computer's video memory directly because 
that might corrupt the actions taken by another process. The same holds 
true for ports or any other direct hardware access. Consider this the 
police state level of the operating system, everything is censored. 


You could consider the next ring (2) confidential. The operating 
system doesn't allow everyone access to this level, but it does allow a 


Ping 0 -This is the application layer. However, many OS/2 device drivers and DLL's 


operate at this level too. OS/2 (like the military) grants and application the 
lowest possible clearance to get the job done. 


Ping 1 -OS/2 does not use this hardware ring, but it is available for specific tasks. 


Ping 2 - This is the layer OS/2 uses for non-critical DLL's and device drivers. It provides 


a higher level of access than the application layer without exposing operating 
specific commands. It allows the kernel to maintain system control. 


Ping 3 - Any OS/2 system files appear at this level. This provides the highest level 


of access that any application can obtain. Only kernel code appears at 
this level. 
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select few applications to use it. OS/2 doesn't provide the 
application with access to anything that could hurt another 
application. It can't trust an application at this level that far. OS/2 
usually places device drivers and DLLs at this layer. They both need 
better access to some of the low-level interfaces than an application 
does. For example, an application running at this level can access 
many of the PC's ports directly. On the other hand, it can't look at 
another processes' memory. This makes sense. A device driver has to 
know about the hardware to do its work. It doesn't need to know 
what another application is doing. 


Figure 8-1 


Consider the next security ring (1) as secret. It's so secret that OS/2 
doesn't use it. Even though an application could theoretically run at 
this level from a hardware point of view, the operating system still 
has to cooperate. Other operating systems use this level for operating 
system components that are not part of the kernel. In other words, an 
application at this level can monitor other applications, but it doesn't 
directly interact with them. 


The last level (0) is top secret. Only the operating system kernel and 
any applications directly attached to it have access to this level. The 
operating system has direct access to everything on the system; it is 
the application in control. This is the level where an application could 
not only damage itself , but also damage every other application on 
the system. This includes locking up the system. Unfortunately, it also 
includes more insidious forms of corruption. For example, an 
application at this level could corrupt memory, then write it out to the 
application's disk files, spreading the corruption even further. The 
next time that the user opened their application files she or he would 
see a big mess rather than a neat spreadsheet. As you can see, these 
layers of protection are essential to smooth operations within a 
multitasking environment. 


Of course, memory protection doesn't stop there. It goes much 
further than that. Consider hardware protection as the first line of 
defense. A truly robust operating system needs more than that. It 
needs some form of monitoring capability that allows it to detect 
problems long before they trigger a hardware solution. 


One of the ways that OS/2 detects application memory errors is the 
use of the flat memory addressing scheme described in the following 
paragraph. The application gets only one selector. To look at the 
memory used by another application, you need that application's 
selector. The minute that an application attempts to do this, OS/2 
gets alerted and prevents the memory corruption. Using a flat 
addressing scheme frees OS/2 from a lot of overhead normally 
associated with monitoring memory accesses. Because each 
application gets only one selector, it becomes easier to simply look 
for an application using the wrong selector than to compare each 
memory access to a list of active selectors and then to the application 
that owns it. 


Virtual memory 


Virtual memory is one of those gray areas that many programmers 
think that they understand, but few really do, especially from the 
OS/2 point of view. The biggest advantage of virtual memory is that 
it frees you from the physical memory constraints of the host 
machine. The CPU under direction of the operating system uses the 
hard drive to provide the additional memory that an application 
requires in addition to the real memory on the machine. Using a 
memory scheme of this nature means that you can no longer assume 
that the piece of data that you accessed five minutes ago is where 
you left it. The operating system moves memory between physical 
memory and disk to accommodate changing application needs. 
Because of this movement and the fact that several applications 
probably share the physical memory on the host machine, you should 
never assume anything about the memory that you use in an 
application. Unlike DOS, you must allow OS/2 to manage the 
memory for you. This is the reason that most of the DOS memory 
functions only allocate or free memory. OS/2 takes care of every 
other aspect of memory management for you. 


OS/2 also uses the flat memory model of the 80386 and above 
processors, which affects the way that you need to look at virtual 
memory. Using the flat memory model is supposed to make OS/2 
more portable to other systems. However, the big difference to the 
programmer is that you no longer have to worry about the segmented 
memory scheme that DOS used. Each OS/2 application has its own 
0-based linear address space. Changing memory locations is a matter 
of changing the offset, there are no segment considerations. This is 
why OS/2 uses the term memory object when referring to a piece of 
memory. 


This isn't your only consideration when using virtual memory under 
OS/2. Some programmers assume that you have the vast resources of 
the 80386 and above processors at your disposal. According to the Intel 
documentation for the 80386, you should have 4GB of address space 
when using the flat memory model. In truth, virtual memory on an 
OS/2 machine is limited to 512MB per application. Part of the reason 
for this limitation is that OS/2 needs to maintain compatibility between 


the 32-bit and 16-bit code combination that most applications use. This 
means that you still can build a very large. application, but not one as 
large as the physical capabilities of the CPU. 


Overall, OS/2 is a paged virtual memory system that uses the flat 
memory model. The paged part of this equation is the subject that gets 
many programmers into trouble. OS/2 uses 4K pages for memory 
allocation. The pages can reside on the hard disk or within physical 
memory. If your application requests a piece of memory that no longer 
resides in physical memory, then the CPU generates a page fault. OS/2 
intercepts this fault, places your application on hold, retrieves the 
contents of that memory page from disk, makes any required changes to 
the memory request, and restarts your application. Your application 
never knows that this happened and even you wouldn't notice it except 
for the occasional application slow down that you see as OS/2 reads 
from disk. When OS/2 needs more physical memory to store pages that 
currently appear on disk, it uses a complicated scheme to determine 
which page it should read from memory to disk, it then replaces that 
page with the page the application requested from disk. 


This means that OS/2 probably doesn't read your entire application 
from disk when you start it. This means that you need to consider this 
problem when creating your application. Try to keep routines that 
execute together in the same area of the application. This actually 
will reduce the number of page faults that your application will see 
and increase application speed by a small amount. OS/2 uses the 
term process for each application that executes under it. 


Now that you have a good picture of memory under OS/2, there is 
one last item that you need to consider. OS/2 supports two types of 
data memory access: private and shared. You use private memory for 
most of an application's variables and internal processing. Shared 
memory comes into play when more than one process requires access 
to the same piece of memory. This is another memory protection 
feature of OS/2. You actually go through a special call to allow two 
processes to share a memory block. This allows you to send messages 
from one application to the next. It also allows both processes to 
receive the same input. OS/2 provides semaphores and other 
mechanisms that allow you to synchronize two applications. You also 
can send another application a standard message using the WIN 
function capabilities. 


=:i_i:.=±:i:_±:=E:=E= 


DEC HEX Character 


0 0 NULL (NUL) 


1 1 © Start of header 


(SOH) 


2 2 © Startof text(STX) 


3 3 v End of text(ETX) 


4 4 . Endof 


transmission (EOT) 


5 5 + Enquire (ENQ) 


6 6 A Acknowledge 


(ACK) 


7 7 . Bell(BEL) 


8 8 I Backspace (BS) 
- 


9 9 o Horizontal tab 


(HT) 


10 A E Line feed (LF) 


11 8 cJ vertical tab (VT) 


12 C 9 Form feed (FF) 


13 D I Carriage return 


(CR) 


14 E J] Shiftout(SO) 


15 F * Shiftin(SI) 


DEC HEX Character 


16 10 > Data link escape 


(DLE) 


17 11 i Device control 1 


(DC1) 


18 12 ¢ Devicecontrol 2 


(DC2) 


19 13 !! Device control 3 


(DC3) 


20 14 ffl Device control 4 


(DC4) 


21 15 § Negative 


acknowledge (NAK) 


22 16 _ Synchronousidle 


(SYN) 


23 17 i End of transmission 


block (ETB) 


24 18 1 Cancel(CAN) 


25 19 J Endof medium 


(EM) 


26 1A i Substitute(SUB) 


27 18 i Escape(ESC) 


281C L Fileseparator(FS) 


29 1D ® Groupseparator 


(GS) 


DEC HEX Character 


30 1E A Record separator 


(RS) 


31 1F T unitseparator(US) 


32 20 Space(SP) 


33 21 ! 


34 22 " 


35 23 # 


36 24 $ 


3 7 25 0/o 


38 26 & 


39 27 ' 


40 28 ( 


41 29 ) 


42 2A * 


43 28 + 


442C 


452D 


46 2E . 


47 2F / 


48 30 0 


DEC HEX Character 


49 31 1 


50 32 2 


51 33 3 


52 34 4 


53 35 5 


54 36 6 


55 37 7 


56 38 8 


57 39 9 


58 3A : 


59 38 ; 


60 3C < 


613D 


62 3E > 


63 3F ? 


64 40 @ 


65 41 A 


66 42 8 


67 43 C 


DEC HEX Character 


68 44 D 


69 45 E 


70 46 F 


71 47 G 


72 48 H 


73 49 I 


74 4A J 


75 48 K 


76 4C L 


77 4D M 


78 4E N 


79 4F 0 


80 50 P 


81 51 Q 


82 52 R 


83 53 S 


84 54 T 


85 55 U 


86 56 V 


DEC HEX Character 


87 57 W 


88 58 X 


90 5A Z 


91 58 [ 


92 5C \ 


93 5D ] 


94 5E ^ 


955F 


96 60 ` 


97 61 a 


98 62 b 


99 63 c 


100 64 d 


101 65 e 


102 66 f 


103 67 9 


104 68 h 


105 69 i 


106 6A j 


DEC HEX Character 


107 68 k 


108 6C I 


109 6D in 


110 6E n 


111 6F o 


112 70 p 


113 71 q 


114 72 r 


115 73 s 


116 74 t 


117 75 u 


118 76 v 


119 77 w 


120 78 x 


121 79 y 


122 7A z 


123 78 ( 


124 7C : 


125 7D ) 


DEC HEX Character 


126 7E - 


127 7F A Delete (DEL) 


128 80 C 


129 81 tl 


130 82 6 


131 83 a 


132 84 a 


133 85 a 


134 86 a 


135 87 C 


136 88 e 


137 89 a 


138 8A a 


139 88 .1. 


140 8C i 


141 8D i 


142 8E A 


143 8F A 


144 90 i 


DEC HEX Character 


145 91 ae 


146 92 i4= 


^ 


147 93 o 


148 94 6 


149 95 6 


150 96 ti 


151 97 tl 


152 98 V 


153 99 0 


I, 


154 9A U 


155 98 ¢ 


156 9C £ 


157 9D ¥ 


158 9E ft 


159 9F I 


160 A0 a 


161 Al i 


162 A2 6 


163 A3 a 


DEC HEX Character 


164 A4 Fi 


165 A5 N 


166 A6 a 


16J A:I o_ 


168 A8 C 


169 A9 r 


170 AA 1 


171 AB 1/2 


172 AC 1/4 


173 AD I 


174 AE « 


175 AF » 


176 80 


177 81 


178 82 


179 83 


180 84 


181 85 


182 86 


ELEL 


DEC HEX Character 


183 87 11 


184 88 ] 


185 89 il 


186 BA 11 


187 88 ffl 


188 BC i 


189 BD Jl 


190 BE I 


191 BF 1 


192 C0 L 


193 C1 i 


194 C2 T 


195 C3 L 


196 C4 


197 C5 + 


198 C6 F 


199 C7 11 


200 C8 L[ 


201 C9 FT 


DEC HEX Character 


202 CA JL 


203 CB if 


204 CC 1[ 


205 CD 


206 CE # 


207 CF ± 


208 D0 u 


209 DI i 


210 D2 lT 


211 D3 LL 


212 D4 E 


213 D5 F 


214 D6 IT 


215 D7 lL 


216 D8 i 


217 D9 J 


218 DA r 


219 DB I 


220 DC I 


DEC HEX Character 


221 DD I 


222 DE I 


223 DF I 


224 E0 o( 


225 El p 


226 E2 I 


227 E3 7t 


228 E4 Z 


229 E5 a 


230 E6 u 


231 E7 T 


232 E8 a 


233 EA o 


234 EB a 


235 EC 8 


236 ED co 


237 ED ¢ 


238 EE e 


DEC HEX Character 


239 EF fl 


240 FO 


241 F1 ± 


242 F2 i 


243 F3 < 


244 F4 I 


245 F5 J 


246 F6 


247 F7 


248 F8 o 


249 F9 . 


250 FA . 


251 FB ly 


252 FC 11 


253 FD 2 


254 FE I 


255 FF 


ASC[I chart organized bv +vpe 


All ASCII codes are given in decimals notation 


Arrot„s 


24t 


27+ i26 


J 
25 


Single horizontal, single Vertical line boxes 


196 194 


218 r - T I 191 


195 L197 + i 180 


179| I |179 


192 L - i J 217 


196 193 


Single horizontal, double Vertical box 


196 210 


214IT iT ii 183 


199 || 215 |L || 182 


186|| || || 186 


2|1EL ± J] 189 


196 207 


Double horizontal, single Vertical box 


205 209 


213F I ] 184 


198 F 216 ± i 181 


179| I |179 


212E ± I 190 


205 207 


Double horizontal, double Vertical box 


205 203 


201 rF = if ii 187 


204 |[ 206 # j| 185 


186|| || || 186 


200 u = It u 188 


205 202 


Foreign language characters 


AAaaaaaa 


142 143 131 132 133 134 160 166 


C9 


128 135 


E 6 e E; 


144 130 136 137 


^ \ , 


LI L! IT " 


139 140 141 161 


NFi 


165 164 
06 


153 147 


Uu 


154 129 


VR 


152 146 
¢£ 


155 156 


6660 


148 149 162 167 
^\, 
uuu 


150 151 163 


a3t1 


145 168 173 
¥ptI 


157 158 159 


Mathematical symbols 


1/2 1/4 


171 172 


0It 


229 230 


coo 


236 237 
<r 


243 244 
•V 


250 251 


ore 


224 225 
ti 


231 232 
en 


238 239 


J 


r7tZ 
226 227 228 


0Q8 


233 234 235 


±2 


240 241 242 


245 246 247 248 249 


112 


252 253 


a:E=E:E=E=EE=E==:a 


HIS appendix provides a basic listing of the error codes that 
OS/2 returns for standard functions, allowing you to find 


unexpected error returns for specific functions. Even though the 
function listings in this book provide a list of every documented error 
code return, there are instances where you might receive an 
unexpected error number. Unfortunately, even this appendix might 
not provide a complete list of every error code returned by 
undocumented functions. In this case, a call to the technical support 
department of the vendor who wrote your compiler is in order. 
(Many of them do not bother to fully document each error; they 
simply provide a list of error numbers.) There are several groups of 
error codes. Each group represents a specific function type. The 
following paragraphs describe these error code groupings. 


Pn°dsv[KOBpr'rong9Taes 


Table 8-1 provides a complete listing of the error codes for the 
DOS, KBD, MOU, and VIO functions described in various chapters 
of this book. This table might or might not contain a complete list of 
error codes, because some of these functions contain undocumented 
features and some compiler vendors support their own special 
functions. IBM left many of the original error returns codes as 
reserved or undefined, leaving blanks for other vendors to use. In 
addition, there are instances where an unexpected action of the 
programmer's part can produce an unexpected return. The error 
code returned might not appear to match anything associated with 
the function that received it. In many cases, you can narrow this 
down to one of three causes: there was an unexpected hardware 
error, you supplied the wrong parameter type or information to the 
function, or the user performed some unexpected action. 


The table does not provide descriptions for every error code. This 
usually occurs because the vendor documentation does not contain 
any description for the error code and no function uses it. In most 
cases, the definition column contains enough information for you to 
derive the meaning of the error within the context of the function 
that returned it. 


Table 8-1 
DOS, KBD, MOU, and VIO function error code summary 


Code Definition 


18 


NO ERROR 


ERROR INVALID FUNCTION 


ERROR FILE NOT FOUND 


ERROR PATH NOT FOUND 


ERROR TOO MANY OPEN FILES 


ERROR ACCESS DENIED 


ERROR INVALID HANDLE 


ERROR ARENA TRASHED 


ERROR NOT ENOUGH MEMORY 


ERROR INVALID BLOCK 


ERROR BAD ENVIRONMENT 


ERROR BAD FORMAT 


ERROR INVALID ACCESS 


ERROR INVALID DATA 


N/A 


ERROR INVALID DRIVE 


ERROR CURRENT DIRECTORY 


ERROR NOT SAME DEVICE 


ERROR NO MORE FILES 


Description 


No error, the function returned 
successfully. 


Invalid function number. 


File not found. 


Path not found. 


Too many files open, increase the 
number of file handles. 


Access denied. This might mean 
that the file is in use by another 
process or that it contains the wrong 
attributes. 


Invalid handle. 


Memory control blocks destroyed. 


Insufficient memory, ask the user to 
close one or more applications to 
free memory. Alternatively, they 
could reduce the number of hard 
disk files to free space for the swap 


file`. 


Invalid memory block address. 


Invalid environment. 


Invalid format. 


Invalid access code. 


Invalid data. This could reference a 
corrupted memory block. 


Reserved error code. 


Invalid drive specified. 


Attempting to remove current 
directory. This can occur if you try 
to change the attributes of the 
current directory. 


A device context, handle, or other 
pointer no longer refers to the same 
device. 


No more files to process. 


Code 


19 


20 


Definition 


ERROR WRITE PROTECT 


ERROR BAD UNIT 


ERROR NOT READY 


ERROR BAD COMMAND 


ERROR CRC 


ERROR BAD LENGTH 


ERROR SEEK 


ERROR NOT DOS DISK 


ERROR SECTOR NOT FOUND 


ERROR OUT OF PAPER 


ERROR WRITE FAULT 


ERROR READ FAULT 


ERROR GEN FAILURE 


ERROR SHARING VIOLATION 


ERROR LOCK VIOLATION 


ERROR WRONG DISK 


ERROR FCB UNAVAILABLE 


ERROR SHARING BUFFER 


EXCE-EDED 


ERROR CODE PAGE MISMATCHED 


Description 


Attempted to write to a write- 
protected (floppy) or nonwriteable 
(CD-ROM) disk. 


Unknown unit. This can occur if the 
device experiences some type of 
failure or if the cable becomes 
disconnected. 


Drive not ready. This often occurs 
when the user forgets to close the 
floppy drive door. 


Unknown command. 


Data error during a cyclic 
redundancy check. This usually 
refers to disk media. 


Invalid request structure length. 


Seek error. This usually occurs 
during a disk or tape seek. A tape 
seek error simply might indicate an 
unformatted or corrupted tape. 


Unknown media type. 


Sector not found. This usually refers 
to a disk error. 


Printer is out of paper. 


Write fault. 


Read fault. 


General failure. OS/2 could not 
return a specific error to describe 
the fault. 


Two processes tried to access a 
nonshareable file or other resource. 


Lock violation. 


Invalid disk change. Usually occurs 
when the user changes the floppy in 
the middle of an operation. 


File control block (FCB) unavailable. 


Sharing buffer overflow. 


Code page does not match. 
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Code D efinition 


ERROR HANDLE EOF 


ERROR HANDLE DISK FULL 
N/A 


ERROR NOT SUPPORTED 


ERROR REM NOT LIST 


ERROR DUP NAME 


ERROR BAD NETPATH 


ERROR NET\IVORK BUSY 


ERROR DEV NOT EXIST 


ERROR TOO MANY CMDS 


ERROR ADAP HDW ERR 


ERROR BAD NET RESP 


ERROR UNEXP NET ERR 


ERROR BAD REM ADAP 


ERROR_PRINTQ_FULL 


ERROR NO SPOOL SPACE 


Description 


End of file (EOF) reached; there is 
no more data to process. 


Disk is full. 
Reserved-Some libraries might 
return error codes in this area. Refer 
to your vendor documentation for 
specifics. 


Network request not supported. 


Remote network node is not online. 
This error also occurs if the remote 
network experiences cabling or 
other hardware related problems. 


Duplicate network filename. 


Network path not found. 


Network is busy. This error can 
occur during peak load periods as 
the result of certain hardware 
failures. 


Device is not installed on the 
network, is not connected through a 
remote network, or experienced a 
failure. 


Network command limit reached. 


Network adapter hardware error or 
cable failure. This error can occur 
with a faulty terminator on ethernet 
networks. 


Incorrect network response. Check 
the lines for noise. 


Unexpected network error. 


The remote network adapter failed. 
This could indicate a faulty cable or 
terminator as well. 


Network print queue is full. 


The print spool file is full. This 
usually happens when the hard drive 
gets full. Try reducing the number of 
files. 


Code 


63 


80 


81 


82 


83 


84 


85 


Definition 


ERROR PRINT CANCELLED 


ERROR NETNAME DELETED 


ERROR NETWORK ACCESS DENIED 


ERROR BAD DEV TYPE 


ERROR BAD NET NAME 


ERROR TOO MANY NAMES 


ERROR TOO MANY SESS 


ERROR SHARING PAUSED 


ERROR_REQ_NOT_ACCEP 


ERROR REDIR PAUSED 


ERROR SBCS ATT WRITE PROT 


ERROR SBCS GENERAL FAILURE 


N/A 


ERROR FILE EXISTS 


ERROR DUP FCB 


ERROR CANNOT MAKE 


ERROR FAIL 124 


ERROR OUT OF STRUCTURES 


ERROR ALREADY ASSIGNED 


Description 


The print spool file got deleted or 
corrupted. This can occur if 
someone renamed the file. 


Network name deleted. 


Network access denied. Check to 
see if all the drivers are loaded and 
the user logged in. 


Invalid device type for a network. 


Network name not found. 


Network name limit exceeded. 


Network session limit exceeded. 


Temporary pause in network. 


Network request denied. Make sure 
the user has appropriate access 
rights. 


Pause in network print disk 
redirection. 


Attempted to write on a protected 
disk. 


General failure, single-byte character 
set. 


Reserved-Some libraries might 
return error codes in this area. Refer 
to your vendor documentation for 
specifics. Some vendors define error 
75 as follows: 
ERROR XGA OUT MEMORY. 
This indrcates : display adapter out 
of memory condition. 


File exists. 


Duplicate file control block (FCB). 
Reserved for operating system use. 


Cannot make directory entry. 


Failure on interrupt 24 (usually 
occurs during a disk failure). 


Too many redirections. 


Duplicate redirection. 
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Code 


86 


87 


95 
96-98 


99 


100 


101 


102 


103 


104 


105 


106 


Definition 


ERROR INVALID PASSWORD 


ERROR INVALID PARAMETER 


ERROR NET WRITE FAULT 


ERROR NO PROC SLOTS 


ERROR NOT FROZEN 
ERROR-SYS -COMP NOT LOADED 


ERR TSTOVFL 


ERR TSTDUP 


ERROR NO ITEMS 


N/A 


ERROR INTERRUPT 


N/A 


ERROR DEVICE IN USE 


ERROR TOO MANY SEMAPHORES 


ERROR EXCL SEM ALREADY 


OwN_ED 


ERROR SEM IS SET 


ERROR_TOO_MANY_SEM_REQUESTS 


ERROR INVALID AT INTERRUPT 


TIME_ 


ERROR SEM OWNER DIED 


ERROR SEM USER LIMIT 


Description 


User entered an invalid password. 


Function or process passed an 
invalid parameter. 


Error writing to a network device. 


No process slots available. 


System failure. This could refer to a 
fatal hardware or software 
(operating system) failure. 


Timer service table overflow. 


Timer service table duplicate. 


No items to work on. 


Reserved-Some libraries might 
return error codes in this area. Refer 
to your vendor documentation for 
specifics. 


Interrupted system call. 


Reserved-Some libraries might 
return error codes in this area. Refer 
to your vendor documentation for 
specifics. 


Device in use by another process. 


User/system open semaphore limit 
reached. 


Exclusive semaphore already owned. 


The DOsclosesemaphore function 
found the semaphore set. 


Too many exclusive semaphore 
requests. 


Operation invalid at interrupt time. 


The previous owner of this 
semaphore terminated without 
freeing it. 


Semaphore limited exceeded. 


Code 


107 


108 


109 


110 


111 


Definition 


ERROR DISK CHANGE 


ERROR DRIVE LOCKED 


ERROR BROKEN PIPE 


ERROR OPEN FAILED 


ERROR BUFFER OVERFLOW 


ERROR DISK FULL 


ERROR NO MORE SEARCH 


HANbLE5 


ERROR INVALID TARGET HANDLE 


ERROR PROTECTION VIOLATION 


ERROR_VIOKBD_REQUEST 


ERROR INVALID CATEGORY 


ERROR INVALID VERIFY SWITCH 


ERROR BAD DRIVER LEVEL 


ERROR CALL NOT IMPLEMENTED 


ERROR SEM TIMEOUT 


Description 


The user either inserted the drive 8 
disk into A or you need to ask them 
to insert the drive 8 disk into A. For 
example, during a diskcopy 
operation from drive A to drive A. 


Drive locked by another process. 


There is no reader for this pipe. You 
cannot write to it. 


Open or create failed due to an 
explicit fail command. 


Buffer that was passed to the system 
call was too small to hold the return 
data. Allocate a larger buffer or 
change the value of any buffer 
length parameters passed during the 
call. 


The disk is full. Remove any 
unneeded files to make space. 


Cannot allocate another search 
structure and handle. 


Target handle in DOSDupHandle 
invalid. This usually means the target 
does not exist, you used the wrong 
handle, the handle got corrupted, 
the target experienced a failure, or 
the user affected the target in some 
Way. 


Invalid user virtual address. 


Error on display write or keyboard 
read. This is a general VIO and KBD 
function failure, OS/2 did not return 
anything more specific. 


The DOSDevloctl category is not 
defined. Refer to Table 5-2 for a list 
of valid categories. 


Invalid value passed for verify flag. 


Level four driver not found. 


Invalid function called. 


Semaphore API function time-out 
occurred. 
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Code Definition 


122 


123 


124 


125 


126 


127 


128 


129 


130 


131 


132 


137 


138 


139 


140 


ERROR INSUFFICIENT BUFFER 


ERROR INVALID NAME or 
HPFS INVALID V-OLUME CHAR 


ERROR INVALID LEVEL 


ERROR NO VOLUME LABEL 


ERROR MOD NOT FOUND 


ERROR PROC NOT FOUND 


ERROR WAIT NO CHILDREN 


ERROR CHILD NOT COMPLETE 


ERROR DIRECT ACCESS HANDLE 


ERROR NEGATIVE SEEK 


ERROR SEEK ON DEVICE 


ERROR IS JOIN TARGET 


ERROR IS JOINED 


ERROR IS SUBSTED 


ERROR NOT JOINED 


ERROR NOT SUBSTED 


ERROR JOIN TO JOIN 


ERROR SUBST TO SUBST 


ERROR JOIN TO SUBST 


Description 


Data buffer is too small. Allocate a 
larger data buffer or change the 
value of any buffer length 
parameters passed with the call. 


Illegal character or invalid file-system 
name. 


Nonimplemented level for 
information retrieval or setting. 


No volume label found using the 
DOSQueryFslnfo function. 


Module handle not found using 
getprocaddr or getmodhandle. 
Procedure handle not found using 
getprocaddr. 
The DOswaitchild function finds no 
children. 


You did not terminate the 
DOswaitchild function children. 


Handle operation invalid for direct 
disk-access handles. 


Attempting to perform a seek using 
a negative offset. 


Application tried to perform a seek 
on a pipe or device. 


Drive has previously joined drives. 


Drive is already joined. 


Drive is already substituted. 


Cannot delete drive that is not 
joined. 
Cannot delete drive that is not 
substituted. 


Cannot join to a joined drive. 


Cannot substitute to a substituted 
drive. 


Cannot join to a substituted drive. 


Code 


141 


142 


143 


145 


146 


147 


148 


149 


Definition 


ERROR SUBST TO JOIN 


ERROR BUSY DRIVE 


ERROR SAME DRIVE 


ERROR DIR NOT ROOT 


ERROR DIR NOT EMPTY 


ERROR IS SUBST PATH 


ERROR IS JOIN PATH 


ERROR PATH BUSY 


ERROR IS SUBST TARGET 


ERROR SYSTEM TRACE 


ERROR INVALID EVENT COUNT 


ERROR TOO MANY MUXWAITERS 


ERROR INVALID LIST FORMAT 


ERROR LABEL TOO LONG or 
HPFS V-OL LABEL L-ONG 


ERROR TOO MANY TCBS 


ERROR SIGNAL REFUSED 


ERROR DISCARDED 


ERROR NOT LOCKED 


ERROR BAD THREADID ADDR 


ERROR BAD ARGUMENTS 


ERROR BAD PATHNAME 


ERROR SIGNAL PENDING 


ERROR UNCERTAIN MEDIA 


Description 


Cannot substitute to a joined drive. 


Specified drive is busy. 


Cannot join or substitute a drive to a 
directory on the same drive. 


Directory must be a subdirectory of 
the root. You cannot use the root 
directory. 


You must specify an empty directory 
to use the join command. 


The path that you specified is used 
in a substitute. 


The path that you specified is used 
in a join. 


Another process is using the 
specified path. 


Cannot join or substitute a drive that 
has a directory that is the target of a 
previous substitute. 
System trace error. 


The DOswaitMuxwaitsem function 
experienced an error. 


System limit of 100 entries reached. 


Invalid list format. 


The volume label that you specified 
is too large. 


Cannot create another TCB. 


Signal refused. 


The specified segment was 
discarded. 


The specified segment is not locked. 


Invalid thread-identity address. 


Invalid environment pointer. 


Invalid path name passed to exec. 


Signal already pending. 


Error with interrupt 24 mapping. 
This usually occurs with a corrupted 
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-::----_ 


C ode D efinition 


ERROR MAX THRDS REACHED 


ERROR MONITORS NOT 


SUPP-ORTED 


166 
ERROR UNC DRIVER NOT 


INSTALLEB 


167 ERROR LOCK FAILED 


168 ERROR SWAPIO FAILED 


169 ERROR SWAPIN FAILED 


170 ERROR BUSY 


171-172 N/A 


173 


174 


175 


ERROR CANCEL VIOLATION 


ERROR ATOMIC LOCK NOT 


SUPP-ORTED 


ERROR READ LOCKS NOT 


SUPP-ORTE5 


176-179 N/A 


ERROR INVALID SEGMENT NUMBER 


ERROR INVALID CALLGATE 


ERROR INVALID ORDINAL 


Description 


floppy or if the user attempts to 
perform a floppy disk operation 
without placing a disk in the drive. 


No more process slots. 


Error with interrupt 24 mapping. 
This usually occurs with a corrupted 
floppy or if the user attempts to 
perform a floppy disk operation 
without placing a disk in the drive. 


This is the default redirection return 
code. 


Locking failed. 


Swap I/0 failed. 


Swap in failed. 


Segment is busy. 


Reserved-Some libraries might 
return error codes in this area. Refer 
to your vendor documentation for 
specifics. Error 171 often returns an 
INT TOO LONG error. 


A lock request is not outstanding for 
the specified file range or the file 
length is zero. 


The file-system driver (FSD) does not 
support atomic lock operations. 
OS/2 versions prior to 2.0 do not 
support atomic lock operations. 


The file-system driver (FSD) does not 
support shared read locks. 


Reserved-Some libraries might 
return error codes in this area. Refer 
to your vendor documentation for 
specifics. 


Invalid segment number. 


Invalid call gate. 


Invalid ordinal. 


Code 


183 


184 


185 


191 


195 


196 


197 


Definition 


ERROR ALREADY EXISTS 


ERROR NO CHILD PROCESS 


ERROR CHILD ALIVE NOWAIT 


ERROR INVALID FLAG NUMBER 


ERROR SEM NOT FOUND 


ERROR INVALID STARTING 


CODESEG 


ERROR INVALID STACKSEG 


ERROR INVALID MODULETYPE 


ERROR INVALID EXE SIGNATURE 


ERROR EXE MARKED INVALID 


ERROR BAD EXE FORMAT 


ERROR ITERATED DATA EXCEEDS 


64K 


ERROR INVALID MINALLOCSIZE 


ERROR DYNLINK FROM INVALID 


RING- 


ERROR IOPL NOT ENABLED 


Description 


Shared segment already exists. 


There is no child process to wait for. 


You specified Nowait and the child 
is alive. 


Invalid flag number. 


Semaphore does not exist. 


Invalid starting code segment or an 
incorrect END (label) directive. 


Invalid stack segment. 


Invalid module type. You cannot use 
the specified dynamic-link library 
(DLL) as an application. Conversely, 
you cannot use the specified 
application as a DLL. 


Invalid EXE signature (the characters 
at the beginning of an EXE file that 
define an OS/2 executable). If the 
first two letters of the file are MZ, 
then it is most likely a DOS 
application. Otherwise, it is another 
application type. 


The linker detected an error during 
EXE file creation and marked the 
EXE as invalid. 


Invalid EXE format. File is a DOS or 
other operating system application. 


Iterated data exceeds 64K in length 
(one of the segments in the file 
exceeds 64K). 


Invalid minimum allocation size (one 
of the segments in the file is larger 
than the size that you specified). 


Dynamic link from invalid privilege 
level. A level 2 routine cannot link to 
dynamic-link libraries (DLLs). See 
the discussion in chapter 9 for 
further details. 


Input/output privilege level (IOPL) 
not enabled. The user set the IOPL 
entry in CONFIG.SYS to NO. 
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Code D efinition 


201 


206 


207 


ERROR INVALID SEGDPL 


ERROR AUTODATASEG EXCEEDS 


64K. 


ERROR RING2SEG MUST BE 


MOVABLE 


ERROR RELOC CHAIN XEEDS 


SEGL_IM 


ERROR INFLOOP IN RELOC CHAIN 


ERROR ENVVAR NOT FOUND 


ERROR NOT CURRENT CTRY 


ERROR NO SIGNAL SENT 


ERROR FILENAME EXCED RANGE 


ERROR RING2 STACK IN USE 


ERROR META EXPANSION TOO 


LONG 


ERROR INVALID SIGNAL NUMBER 


ERROR THREAD 1 INACTIVE 


ERROR INFO NOT AVAIL 


ERROR LOCKED 


ERROR BAD DYNALINK 


Description 


Invalid segment descriptor privilege 
level. You can use only levels 2 or 3. 


Automatic data segment exceeds 


You must make a privilege level 2 
segment movable. See chapter 9 for 
further details on privilege levels. 


Relocation chain exceeds segment 
limit. 


Infinite loop in relocation chain 
segment. 


Environment variable not found. 


Not current country. 


The application did not send a 
signal. None of the processes in the 
command subtree has a signal 
handler. 


Filename is greater than 8 
characters or extension is greater 
than 3 characters. 


Privilege level 2 stack is in use. Refer 
to chapter 9 for a discussion of 
privilege levels. 


Meta (global) expansion is too long. 


Invalid signal number. 


Inactive thread. 


There is no file system information 
available for this file. This could 
indicate a variety of problems 
including hard disk damage. 


Locked error. 


Your application attempted to 
execute a nonfamily API (non-FAPI) 
function in DOS mode. See chapters 
4 and 5 for the description of FAPI 
KBD, MOU, and VIO functions. 


Code D efinition 


ERROR TOO MANY MODULES 


ERROR NESTING NOT ALLOWED 


ERROR CANNOT SHRINK 


217 


224 


251 


ERROR ZOMBIE PROCESS 


ERROR STACK IN HIGH MEMORY 


ERROR INVALID EXITROUTINE RING 


ERROR GETBUF FAILED 


ERROR FLUSHBUF FAILED 


ERROR TRANSFER TOO LONG 


ERROR FORCENOSWAP FAILED 


ERROR SMG NO TARGET WINDOW 


ERROR NO CHILDREN 


ERROR INVALID SCREEN GROUP 


ERROR BAD PIPE 


ERROR PIPE BUSY 


ERROR NO DATA 


ERROR PIPE NOT CONNECTED 


ERROR MORE DATA 


ERROR VC DISCONNECTED 


ERROR_CIRcUIARlrv_REQUESTED 


ERROR DIRECTORY IN CDS 


Description 


Too many modules. 


Nesting is not allowed. 


This is a nonstandard return value 
provided by some vendors. It usually 
indicates that you cannot reduce the 
size of a data construct. 


Zombie process. This usually 
signifies that the process died. 


The stack is located in high memory. 


Invalid exit routine ring. See chapter 
9 for details on protection rings. 


Get buffer failed. 


Flush buffer failed. 


Data transfer is too long. 


This is a nonstandard return value 
provided by some vendors. It 
indicates that an attempt to force a 
no swap condition failed. 


You created the application window 
without using the FCF_TASKLIST 
style. It also could indicate that 
OS/2 could not create the window 
or already destroyed it. 


No child process. 


Invalid session. 


Nonexistent pipe or invalid 
operation. 


Pipe is busy. 


No data available on nonblocking 
read. 


Pipe was disconnected by server. 


There is more data available. 


Session was dropped due to errors. 


This error occurs when renaming a 
directory would cause circularity 
problems. 
This error occurs when you try to 


Table B-1 Continued 


C ode D efinition 


ERROR INVALID FSD NAME 


ERROR INVALID PATH 


ERROR INVALID EA NAME 


ERROR EA LIST INCONSISTENT 


ERROR EA LIST TOO LONG 


ERROR NO META MATCH 


ERROR FINDNOTIFY TIMEOUT 


259 
ERROR NO MORE ITEMS 


ERROR SEARCH STRUC REUSED 


ERROR CHAR NOT FOUND 


ERROR TOO MUCH STACK 


ERROR INVALID AITR 


ERROR INVALID STARTING RING 


ERROR INVALID DLL INIT RING 


ERROR CANNOT COPY 


ERROR DIRECTORY 


ERROR OPLOCKED FILE 


ERROR OPLOCK THREAD EXISTS 


ERROR VOLUME CHANGED 


Description 


rename a directory that is in use 
(usually by another process). 


Your application tried to access a 
nonexistent file-system driver (FSD). 


Invalid pseudo device. 


Invalid character in name. It also 
could indicate an invalid cbName. 


The EA list contents does not match 
its size or there are invalid EAs in 
the list. 


FEAList is longer than 64K - 1 
bytes. 


String does not match expression. 


This is a nonstandard error value 
provided by some vendors. It 
indicates that a find notify timed-out. 


There are no more items for the 
DOSQueryFSAttach ordinal query. 


DOS mode find first or find next 
search structure reused. 


Character not found. 


Stack request exceeds system limit. 


Invalid attribute. 


Invalid starting ring. See chapter 9 
for details on protection rings. 


Invalid DLL INIT (initialization) ring. 
See chapter 9 for details on 
protection rings. 
Cannot copy. 


DOSCopy experienced an error in 
DOscalll. 


Oplocked file. 


Oplock thread exists. 


The volume changed. This usually 
happens when the user changes a 
floppy unexpectedly. 


Code 


271 


2:I 2' 


273 


276 


Definition 


ERROR FINDNOTIFY HANDLE 


IN USE 


ERROR FINDNOTIFY HANDLE 


CLOSED 


ERROR NOTIFY OBJECT REMOVED 


ERROR ALREADY SHUTDOWN 


ERROR FAS DIDNT FIT 


ERROR EA FILE CORRUPT 


ERROR EA TABLE FULL 


ERROR INVALID EA HANDLE 


ERROR NO CLUSTER 


ERROR CREATE EA FILE 


ERROR CANNOT OPEN EA FILE 


ERROR EAS NOT SUPPORTED 


Description 


Reserved-Some libraries might 
return error codes in this area. Refer 
to your vendor documentation for 
specifics. Many vendors use this 
error to refer to a find notify handle 
error. 


Reserved-Some libraries might 
return error codes in this area. Refer 
to your vendor documentation for 
specifics. Many vendors use this 
error to refer to a find notify handle 
error. 


Reserved-Some libraries might 
return error codes in this area. Refer 
to your vendor documentation for 
specifics. Many vendors use this 
error to refer to a find notify object 
error. 


The system already is shut down. 


The buffer that you provided was 
not large enough to hold the 
extended attributes (EAs). Allocate a 
larger buffer. 


The extended attribute (EA) file 
suffered damage. You usually can fix 
this problem using the CHKDSK 
utility. 


The extended attribute (EA) table is 
full. 


The extended attribute (EA) handle 
is invalid. 


No cluster. This usually indicates 
some type of disk error or invalid 
parameter values. 
Cannot create the extended attribute 
(EA) file. 
Cannot open the extended attribute 
(EA) file. 


Destination file system does not 
support extended attributes (EAs). 
This usually happens during a 
network drive access. 
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Code Definition 


283 


299 


300 


301 


302 


ERROR NEED FAS FOUND 


ERROR DUPLICATE HANDLE 


ERROR DUPLICATE NAME 


ERROR EMPTY MUXWAIT 


ERROR MUTEX OWNED 


ERROR NOT OWNER 


ERROR PARAM TOO SMALL 


ERROR TOO MANY HANDLES 


ERROR TOO MANY OPENS 


ERROR WRONG TYPE 


ERROR UNUSED CODE 


ERROR THREAD NOT TERMINATED 


ERROR INIT ROUTINE FAILED 


ERROR MODULE IN USE 


ERROR NOT ENOUGH 


wATeHpOTNTs 


ERROR TOO MANY POSTS 


ERROR ALREADY POSTED 


ERROR ALREADY RESET 


ERROR SEM BUSY 


N/A 


Description 


The destination file system does not 
support extended attributes (EAs) 
and the source file's EAs contain a 
need EA. 


The handle already exists. 


The name already exists. 


The list of semaphores in a muxwait 
semaphore is empty. 


The calling thread owns one or 
more of the mutex semaphores in 
the list. 


Caller does not own the semaphore. 


Parameter is not large enough to 
hold all the semaphore records in 
the muxwait semaphore. 


Number of handles limit reached. 


There are too many files or 
semaphores open. 


Attempted to create the wrong type 
of semaphore. 


Code is not used. 


Thread was not terminated. 


Initialization routine failed. 


Module in use. 


There are not enough watchpoints. 


An event semaphore reached its 
post count limit. 
The event semaphore already is 
posted. 
The event semaphore already is 
reset. 


The specified semaphore is busy. 


Reserved-Some libraries might 
return error codes in this area. Refer 


Code 


312 


313 


314 


Definition 


ERROR INVALID PROCID 


ERROR INVALID PDELTA 


ERROR NOT DESCENDANT 


ERROR NOT SESSION MANAGER 


ERROR INVALID PCLASS 


ERROR INVALID SCOPE 


ERROR INVALID THREADID 


ERROR DOSSUB SHRINK 


ERROR DOSSUB NOMEM 


ERROR DOSSUB OVERLAP 


ERROR DOSSUB BADSIZE 


ERROR DOSSUB BADFLAG 


ERROR DOSSUB BADSELECTOR 


ERROR MR MSG TOO LONG or 


MGS-MR-MSG-TOO-LONG 


ERROR MR MID NOT FOUND 


ERROR MR UN ACC MSGF 


ERROR MR INV MSGF FORMAT 


ERROR MR INV IVCOUNT 


ERROR MR UN PERFORM 


ERROR TS WAREUP 


ERROR TS SEMHANDLE 


ERROR TS NOTIMER 


Description 


to your vendor documentation for 
specifics. 


Invalid process identifier (PID). 


Invalid priority delta. 


Not a descendent of this process. 


Requester is not the session 
manager. 


Invalid P class. 


Invalid scope. 


Invalid thread identity (TID). 


Cannot shrink the segment using the 
DOSsubsetMem function. 


There is not enough memory to 
satisfy the DOSsubAllocMem 
function request. 


There is an overlap of the block that 
you want to free using 
DOSsubFreeMem with a block of 
allocated memory. 


Invalid size parameter for a 
DOSsubAllocMem or 
DOSsubFreeMem function call. 


Invalid flag parameter for a 
DOSsubsetMem function call. 


Invalid segment selector. 


Message too long for buffer. Allocate 
a larger buffer. 


Message identity number not found. 


Unable to access message file. 


Invalid message file format. 


Invalid insertion variable count. 


Unable to perform function. 


Unable to wake up. 


Invalid system semaphore. 


No timers available. 
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Code 


326 


327 


328 


329 


Definition 


ERROR TS HANDLE 


ERROR TS DATETIME 


ERROR SYS INTERNAL 


ERROR_QUE_CURRENT_NAME 


ERROR_QUE_PROC_NOT_OWNED 


ERROR_QUE_PROC_OWNED 


ERROR_QUE_DUPLICATE 


ERROR_QUE_ELEMENT_NOT_EXIST 


ERROR_QUE_NO_MEMORY 


ERROR_QUE_INVALID_NAME 


ERROR_QUE_INVALID_PRIORITY 


ERROR_QUE_INVALID_HANDLE 


ERROR_QUE_LINK_NOT_FOUND 


ERROR_QUE_MEMORY_ERROR 


ERROR_QUE_PREV_AT_END 


ERROR_QUE_PROC_NO_ACCESS 


ERROR_QUE_EMprv 


ERROR_QUE_NAME_NOT_EXIST 


ERROR_QUE_NOT_INITIALIZED 


ERROR_QUE_UNABLE_TO_ACCESS 


ERROR_QUE_UNABLE_TO_ADD 


Description 


Invalid timer handle. 


Timer date or time is invalid. 


Internal system error. 


The current queue name does not 
exist. 


The current process does not own 
the specified queue. 


The current process owns the 
specified queue. 


Duplicate queue name. 


The specified queue element does 
not exist. 


There is not enough memory to 
meet queue requirements. 


Invalid queue name. 


Invalid queue priority parameter. 


Invalid queue handle. 


Queue link not found. 


Indicates a queue memory error. 
This usually happens when the 
memory gets corrupted. It also could 
indicate a hardware failure. 


Previous queue element marked the 
end of the queue. 


This process does not possess queue 
access. 


Queue is empty. 


Queue name does not exist. 


Queue is not initialized. 


Unable to access queues. 


Unable to add new queue. This 
could indicate an insufficient 
memory condition. 


Definition 


ERROR_QUE_UNABLE_TO_INIT 


N/A 


ERROR VIO INVALID MASK 


ERROR VIO PTR 


ERROR VIO APTR 


ERROR VIO RPTR 


ERROR VIO CPTR 


ERROR VIO LPTR 


ERROR VIO MODE 


ERROR VIO WIDTH 


ERROR VIO AITR 


ERROR VIO ROW 


ERROR VIO COL 


ERROR VIO TOPROW 


ERROR VIO BOTROW 


ERROR VIO RIGHTCOL 


ERROR VIO LEFTCOL 


ERROR SCS CALL 


ERROR SCS VALUE 


ERROR VIO WAIT FLAG 


ERROR VIO UNLOCK 


ERROR SGS NOT SESSION MGR 


ERROR SMG INVALID SGID or 
ERROR-SMG-INVALID-SESSION ID 


ERROR SMG NOSG or 
ERROR-SMG-NO SESSIONS 


ERROR SMG GRP NOT FOUND or 


Description 


Unable to initialize queues. 


Reserved-Some libraries might 
return error codes in this area. Refer 
to your vendor documentation for 
specifics. 


Invalid function replaced. 


Invalid parameter pointer. 


Invalid attribute pointer. 


Invalid row pointer. 


Invalid column pointer. 


Invalid length pointer. 


Screen mode is not supported by 
the display adapter or the device 
driver. 


Invalid cursor width value. 


Invalid cursor attribute value. 


Invalid row value. 


Invalid column value. 


Invalid top row value. 


Invalid bottom row value. 


Invalid right column value. 


Invalid left column value. 


The calling process is the not 
session manager. 


Value is not for save or restore. 


Invalid wait flag setting. 


Screen not previously locked. 


The calling process is not the 
session manager. 


Invalid session identity. 


No sessions available. 


Session not found. This could 
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Code D efinition 


ERROR SMG SESSION NOT FOUND 
or SMG-SESsioN NOT-FOuivD 


372 


386 


ERROR SMG SET TITLE 


ERROR KBD PARAMETER 


ERROR KBD NO DEVICE 


ERROR KBD INVALID IOWAIT 


ERROR KBD INVALID LENGTH 


ERROR KBD INVALID ECHO MASK 
or KBD-INVALID INPU-T MASK 


ERROR KBD INVALID INPUT MASK 


ERROR MON INVALID PARMS 


ERROR MON INVALID DEVNAME 


ERROR MON INVALID HANDLE 


ERROR MON BUFFER TOO SMALL 


ERROR MON BUFFER EMPTY 


ERROR MON DATA TOO IARGE 


ERROR MOUSE NO DEVICE 


ERROR MOUSE INV HANDLE 


ERROR MOUSE INV PARMS 


ERROR MOUSE CANT RESET 


Description 


indicate that the session terminated 
abnormally or that the session is not 
supported. For example, if the user 
did not install DOS or Windows 
support. 


You cannot change the title sent by 
the shell or parent. 


Invalid keyboard parameter. 


There is no keyboard attached to the 
system or the keyboard is faulty. 


Invalid I/0 wait specified. 


Invalid length for keyboard. 


Invalid echo mode mask. 


Invalid input mode mask. 


Invalid DOSMon function 
parameters. 


Invalid device name string. 


Invalid device handle. 


Monitor buffer is too small. Allocate 
a larger buffer. 


Monitor buffer is empty. 


The data record is too large. 


Mouse device is closed. This could 
indicate an invalid handle, an 
inoperative mouse, or lack .of 
support from the operating system. 


Mouse device is closed. This could 
indicate an invalid handle, an 
inoperative mouse, or lack of 
support from the operating system. 


Parameters invalid for the current 
display mode. 


The mouse driver cannot reset the 
mouse. This usually indicates a 
hardware problem. 


Code 


389 


399 


406 


407 


Definition 


ERROR MOUSE DISPIAY PARMS 


ERROR MOUSE INV MODULE 


ERROR MOUSE INV ENTRY PT 


ERROR MOUSE INV MASK 


NO ERROR MOUSE NO DATA 


NO ERROR MOUSE PTR DRAWN 


ERROR_INVALID FREQUENCY 


ERROR NLS NO COUNTRY FILE or 
NO CO-UNTEY S-YS 


ERROR NLS OPEN FAILED or 
OPEN 60UN-TRY S-YS 


ERROR NLS NO CTRY CODE or 
ERROR-NO-COU-NTRY-OR 


CODEPA6E 


ERROR NLS TABLE TRUNCATED 


ERROR NLS BAD TYPE 


ERROR NLS TYPE NOT FOUND or 
COUNT-RY N-O TYPE 


ERROR VIO SMG ONLY 


ERROR VIO INVALID ASCIIZ 


ERROR VIO DEREGISTER 


ERROR VIO NO POPUP 


ERROR VIO EXISTING POPUP 


ERROR KBD SMG ONLY 


Description 


Parameters invalid for the current 
display mode. 


Mouse module is not valid. 


Mouse device driver entry point is 
not valid. 


Function mask invalid. 


No valid mouse data. 


The function drew the mouse 
pointer. 


Invalid beep frequency. 


Cannot find the COUNTRY.SYS 
file. 


Cannot open the COUNTRY.SYS 
file. 


Country code not found. This 
usually means that the country code 
does not exist in the current setup. 
Obtain updated system files. 


The buffer that you provided is too 
small to hold the national language 
support (NLS) table. Allocate a 
larger buffer to retrieve the entire 
table. 


The selected national language 
support (NLS) type does not exist. 


The selected national language 
support (NLS) type does not appear 
in the file. 


Only the session manager can issue 
this call. 


Invalid ASCIIZ length. 


VIODeRegister function not allowed. 


You did not allocate a pop-up 
window. 


The screen already contains a pop- 
up window. 


Only the session manager can issue 
this call. 
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Code 


408 
409 


410 


411 


430 


Definition 


ERROR KBD INVALID ASCIIZ 
ERROR-KBD-INVALID-MASK 


ERROR KBD REGISTER 


ERROR KBD DEREGISTER 


ERROR MOUSE SMG ONLY 


ERROR MOUSE INVALID ASCIIZ 


ERROR MOUSE INVALID MASK 


ERROR MOUSE REGISTER 


ERROR MOUSE DEREGISTER 


ERROR SMG BAD ACTION 


ERROR SMG INVALID CALL 


ERROR SCS SG NOTFOUND 


ERROR SCS NOT SHELL 


ERROR VIO INVALID PARMS 


ERROR VIO FUNCTION OWNED 


ERROR VIO RETURN 


ERROR SCS INVALID FUNCTION 


ERROR SCS NOT SESSION MGR 


ERROR VIO REGISTER 


ERROR VIO NO MODE THREAD 


ERROR VIO NO SAVE RESTORE 


THD 


ERROR VIO IN BG 


ERROR VIO ILLEGAL DURING 


pOpOp 


Description 


Invalid ASCIIZ length. 
Invalid replacement mask. 


You cannot use KBDRegister here. 


You cannot use KBDDeRegister 
here. 


Only the session manager can issue 
this call. 


Invalid ASCIIZ length. 


Invalid replacement mask. 


Mouse register not allowed. 


Mouse deregister not allowed. 


Invalid action specified. 


INIT called more than once. This 
also could indicate an invalid session 
identity. 


New session number. 


Only the shell can issue this call. 


Invalid parameters passed. 


Save and restore functions already 
owned by another process. 


Nondestructive return. Any previous 
actions automatically undone. 


Caller invalid function. 


Only the session manager can issue 
this call. 


VIO register not allowed. 


No mode restore thread in session. 


No save or restore thread in session. 


You cannot issue this call while in 
the background. 


You cannot issue this call during a 
POP-uP. 


Code 


431 


432 


433 


Definition 


ERROR SMG NOT BASESHELL 


ERROR_SMG_BAD_STATUSREQ 


ERROR_QUE_INVALID_WAIT 


ERROR VIO LOCK 


ERROR MOUSE INVALID IOWAIT 


ERROR VIO INVALID HANDLE 


ERROR VIO ILLEGAL DURING LOCK 


ERROR VIO INVALID LENGTH 


ERROR KBD INVALID HANDLE 


ERROR KBD NO MORE HANDLE 


ERROR KBD CANNOT CREATE KCB 


ERROR KBD CODEPAGE LOAD 


INCO_MPL 


ERROR KBD INVALID CODEPAGE ID 


ERROR KBD NO CODEPAGE 


supp_ORT 


ERROR_KBD_FOCUS_REQUIRED 


ERROR KBD FOCUS ALREADY 


ACTivE 


ERROR KBD KEYBOARD BUSY 


ERROR KBD INVALID CODEPAGE 


ERROR KBD UNABLE TO FOCUS 


ERROR SMG SESSION NON SELECT 


ERROR SMG SESSION NOT 


FOREGRN5 


ERROR SMG SESSION NOT PARENT 


ERROR SMG INVALID START MODE 


ERROR SMG INVAIJD REIAIED OPT 


ERROR SMG INVALID BOND 


OpTI_ON 


Description 


Only the base shell can issue this call. 


Invalid status requested. 


Nowait parameter out of bounds 
(too high or low). 


Error returned from Scroll Lock. 


Invalid parameters for IOwait. 


Invalid VIO handle. 


You cannot issue this call during 
screen lock. 


Invalid VIO length. 


Invalid KBD handle. 


Ran out of handles. 


Unable to create KCB. 


Unsuccessful code page load. This 
could indicate a damaged code page 
file or invalid parameters. 


Invalid code page identity. 


No code page support. 


Keyboard focus required. 


Calling thread has outstanding focus. 


The keyboard is busy. 


Invalid code page. 


Focus attempt failed. 


You cannot select this session. 


Parent or child session is not in the 
foreground. 


Calling process is not the parent of 
the requested child. 


Invalid session start mode. 


Invalid session start related option. 


Invalid session bond option. 
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Code Definition 


456 ERROR SMG INVALID SELECT OPT 


457 ERROR SMG START IN 


BAckGRO-UND 


458 ERROR SMG INVALID STOP 


OpTI_ON/ 


459 ERROR SMG BAD RESERVE 


460 ERROR SMG PROCESS NOT 


FARE_NT 


466 


476 


ERROR SMG INVALID DATA 


LENGTH 


ERROR SMG NOT BOUND 


ERROR SMG RETRY SUB ALLOC 


ERROR KBD DETACHED 


ERROR VIO DETACHED 


ERROR MOU DETACHED 


ERROR VIO FONT 


ERROR VIO USER FONT 


ERROR VIO BAD CP 


ERROR VIO NO CP 


ERROR VIO NA CP 


ERROR INVALID CODE PAGE 


ERROR CPLIST TOO SMALL 


ERROR CP NOT MOVED 


ERROR MODE SWITCH INIT 


ERROR CODE PAGE NOT FOUND 


Description 


Invalid session select option. 


Session started in background. 


Invalid session stop option. 


Reserved parameters are not zero. 


Session parent process already 
exists. 


Invalid data length. 


Parent is not bound. 


Retry request block allocation. 


A detached process identifier (PID) 
cannot issue this call. 


A detached process identifier (PID) 
cannot issue this call. 


A detached process identifier (PID) 
cannot issue this call. 


There is no font available to support 
the requested display mode. 


User font is active. 


Invalid code page specified. 


System displays do not support the 
specified code page. 


Current display does not support the 
specified code page. 


Invalid code page. 


Code page list is too small. 


Code page was not moved. 


Mode switch initialization error. This 
could indicate a variety of problems 
including hardware failure or a bad 
device driver. 


Code page was not found. 


Code 


477 


491 


Definition 


ERROR UNEXPECTED SLOT 


RETU-RNED 


ERROR SMG INVALID TRACE 


OpTI_ON 


ERROR VIO INTERNAL RESOURCE 


ERROR VIO SHELL INIT 


ERROR SMG NO HARD ERRORS 


ERROR CP SWITCH INCOMPLETE 


ERROR VIO TRANSPARENT POPUP 


ERROR CRITSEC OVERFLOW 


ERROR CRITSEC UNDERFLOW 


ERROR VIO BAD RESERVE 


ERROR INVALID ADDRESS 


ERROR ZERO SELECTORS 


REQOESTEf5 


ERROR NOT ENOUGH SELECTORS 


AVA_ 


ERROR INVALID SELECTOR 


ERROR SMG INVALID PROGRAM 


TYPE_ 


ERROR SMG INVALID PGM 


CONTROL- 


ERROR SMG INVALID INHERIT OPT 


ERROR VIO EXTENDED SG 


ERROR VIO NOT PRES MGR SG 


ERROR VIO SHIELD OWNED 


ERROR VIO NO MORE HANDLES 


ERROR VIO SEE ERROR LOG 


ERROR VIO ASSOCIATED DC 


Description 


Internal error. 


Invalid start session trace indicator. 


VIO internal resource error. 


VIO shell initialization error. 


No session manager hard errors. 


The DOssetprocesscp function 
cannot set the KBD or VIO code 
Page. 


Error during a VIO pop-up window. 


Critical section overflow. 


Critical section under flow. 


Reserved parameter is not zero. 


Invalid physical address. 


You must request at least one 
selector when using this function. 


There is not enough global 
descriptor table (GDT) space to 
satisfy the request. 


This is not a global descriptor table 
(GDT) selector. 


Invalid program type. 


Invalid program control. 


Invalid inherit option. 


Invalid in PM session. 


Only the session manager can issue 
this call. 


Another process owns the VIO 
shield. 


No more VIO handles. 


Check the error log. 


The presentation space already is 
associated with a device context. 


Table 8-1 
Continued 


Code Definition 


ERROR KBD NO CONSOLE 


ERROR MOUSE NO CONSOLE 


ERROR MOUSE INVALID HANDLE 


ERROR SMG INVALID DEBUG 


pARrris 


ERROR KBD EXTENDED SG 


ERROR MOU EXTENDED SG 


ERROR SMG INVALID ICON FILE 


ERROR TRC PID NON EXISTENT 


ERROR TRC COUNT ACTIVE 


ERROR TRC SUSPENDED BY 


couivT 


ERROR TRC COUNT INACTIVE 


ERROR TRC COUNT REACHED 


ERROR NO MC TRACE 


ERROR MC TRACE 


ERROR TRC COUNT ZERO 


ERROR SMG TOO MANY DDS 


ERROR SMG INVALID 


NOTI-FICAT-ION 


ERROR LF INVALID FUNCTION 


ERROR LF NOT AVAIL 


ERROR LF SUSPENDED 


ERROR LF BUF TOO SMALL 


ERROR LF BUFFER CORRUPTED 


ERROR LF BUFFER FULL 


ERROR LF INVALID DAEMON 


ERROR LF INVALID RECORD 


Description 


There is no console associated with 
the keyboard. 


There is no console associated with 
the mouse. 


Invalid mouse handle. 


Invalid session manager debug 
parameters. 


Invalid in PM session. 


Invalid in PM session. 


Invalid icon file. 


The process identifier (PID) does not 
exist. 


Code D efinition 


523 ERROR LF INVALID TEMPL 


523 ERROR LF INVALID SERVICE 


524 ERROR LF GENERAL FAILURE 


525 ERROR LF INVALID ID 


526 ERROR LF INVALID HANDLE 


527 ERROR LF NO ID AVAIL 


528 ERROR LF TEMPLATE AREA FULL 


529 ERROR LF ID IN USE 


530 ERROR MOU NOT INITIALIZED 


531 ERROR MOUINITREAL DONE 


532 ERROR DOSSUB CORRUPTED 


542 
543 
544 
545 
546 
547 
548 


ERROR MOUSE CALLER NOT 


SU85YS 


ERROR ARITHMETIC OVERFLOW 


ERROR TMR NO DEVICE 


ERROR TMR INVALID TIME 


ERROR PVVI/ INVALID ENTITY 


ERROR PVW INVALID ENTITY TYPE 


ERROR PVVI/ INVALID SPEC 


ERROR PVVI/ INVALID RANGE TYPE 


ERROR PVW INVALID COUNTER 


BLK 


ERROR PVW INVALID TEXT BLK 


ERROR PRF NOT INITIALIZED 


ERROR PRF ALREADY INITIALIZED 


ERROR PRF NOT STARTED 


ERROR PRF ALREADY STARTED 


ERROR PRF TIMER OUT OF RANGE 


ERROR PRF TIMER RESET 


549-638 N/A 


Description 


The suballocation memory pool 
previously initialized by 
DOSsubsetMem is corrupt. 


Reserved-Some libraries might 
return error codes in this area. Refer 
to your vendor documentation for 
specifics. 
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639 ERROR VDD LOCK USEAGE DENIED 


640 ERROR TIMEOUT 


641 ERROR VDM DOWN 


642 ERROR VDM LIMIT 


643 ERROR VDD NOT FOUND 


ERROR INVALID CALLER 


645 ERROR PID MISMATCH 


646 ERROR INVALID VDD HANDLE 


647 ERROR VLPT NO SPOOLER 


648 ERROR VCOM DEVICE BUSY 


649 ERROR VLPT DEVICE BUSY 


650 ERROR NESTING TOO DEEP 


651 ERROR VDD MISSING 


652-670 N/A 


ERROR BIDI INVALID LENGTH 


ERROR BIDI INVALID INCREMENT 


ERROR BIDI INVALID COMBINATION 


ERROR BIDI INVALID RESERVED 


ERROR BIDI INVALID EFFECT 


ERROR BIDI INVALID CSDREC 


ERROR BIDI INVALID CSDSTATE 


ERROR BIDI INVALID LEVEL 


ERROR BIDI INVALID TYPE 


supp_ORT_ 


ERROR BIDI INVALID ORIENIAI`ION 


ERROR BIDI INVALID NUM SHAPE 


Description 


The semaphore timed out. 


OS/2 could not find the requested 
virtual device driver IVDD). 


An invalid caller used this function to 
open, close, or request a virtual 
device driver OVDD). 


Nesting level too deep. 


Reserved-Some libraries might 
return error codes in this area. Refer 
to your vendor documentation for 
specifics. 


C ode D efinition 


682 ERROR BIDI INVALID CSD 


683 ERROR BIDI NO SUPPORT 


684 NO ERROR BIDI RW INCOMPLETE 


685-690 N/A 


691 ERROR IMP INVALID PARM 


692 ERROR IMP INVALID LENGTH 


693 MSG HPFS DISK ERROR WARN 
694-729 N/A 


730 ERROR MON BAD BUFFER 


731 ERROR MODULE CORRUPTED 


1477 ERROR SM OUTOF SWAPFILE 


2055 ERROR LF TIMEOUT 


2057 ERROR LF SUSPEND SUCCESS 


2058 ERROR LF RESUME SUCCESS 


2059 ERROR LF REDIRECT SUCCESS 


2060 ERROR LF REDIRECT FAILURE 


32768 ERROR SWAPPER NOT ACTIVE 


32769 ERROR INVALID SWAPID 


32770 ERROR IOERR SWAP FILE 


32771 ERROR SWAP TABLE FULL 


32772 ERROR SWAP FILE FULL 


32773 ERROR CANT INIT SWAPPER 


32774 ERROR SWAPPER ALREADY INIT 


32775 ERROR PMM INSUFFICIENT 


MEM-ORY 


32776 ERROR PMM INVALID FLAGS 


32777 ERROR PMM INVALID ADDRESS 


Description 


Reserved-Some libraries might 
return error codes in this area. Refer 
to your vendor documentation for 
specifics. 


Reserved-Some libraries might 
return error codes in this area. Refer 
to your vendor documentation for 
specifics. 
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Code Definition 


32778 ERROR PMM LOCK FAILED 


32779 ERROR PMM UNLOCK FAILED 


32780 ERROR PMM MOVE INCOMPLETE 


32781 ERROR UCOM DRIVE RENAMED 


32782 ERROR UCOM FILENAME 


TRUNCATED- 


32783 ERROR UCOM BUFFER LENGTH 


32784 ERROR MON CHAIN HANDLE 


32785 ERROR MON NOT REGISTERED 


32786 ERROR SMG ALREADY TOP 


32787 ERROR PMM ARENA MODIFIED 


32788 ERROR SMG PRINTER OPEN 


32789 ERROR PMM SET FLAGS FAILED 


32790 ERROR INVALID DOS DD 


32791 ERROR BLOCKED 


32792 ERROR NOBLOCK 


32793 ERROR INSTANCE SHARED 


32794 ERROR NO OBJECT 


32795 ERROR PARTIAL AmACH 


32796 ERROR INCACHE 


32797 ERROR SWAP IO PROBLEMS 


32798 ERROR CROSSES OBJECT 


BOUNDARY 


32799 ERROR LONGLOCK 


32800 ERROR SHORTLOCK 


32801 ERROR UVIRTLOCK 


Description 


The requested memory object 
crosses the boundary of another 
memory object. 


Code D efinition 


32802 ERROR ALIASLOCK 


32803 ERROR ALIAS 


32804 ERROR NO MORE HANDLES 


32805 ERROR SCAN TERMINATED 


32806 ERROR TERMINATOR NOT FOUND 


32807 ERROR NOT DIRECT CHILD 


32808 ERROR DELAY FREE 


32809 ERROR GUARDPAGE 


32900 ERROR SWAPERROR 


32901 ERROR LDRERROR 


32902 ERROR NOMEMORY 


32903 ERROR NOACCESS 


32904 ERROR NO DLL TERM 


65026 ERROR CPSIO CODE PAGE INVALID 


65027 ERROR CPSIO NO SPOOLER 


65028 ERROR CPSIO FONT ID INVALID 


65033 ERROR CPSIO INTERNAL ERROR 


65034 ERROR CPSIO INVALID PTR NAME 


65037 ERROR CPSIO NOT ACTIVE 


65039 ERROR CPSIO PID FULL 


65040 ERROR CPSIO PID NOT FOUND 


6 5 0 43 ERRO R_CPSIO_READ_CTL_SEQ 


65045 ERROR CPSIO READ FNT DEF 


65047 ERROR CPSIO WRITE ERROR 


65048 ERROR CPSIO WRITE FULL ERROR 


65049 ERROR CPSIO WRITE HANDLE BAD 


65074 ERROR CPSIO SWIT LOAD 


65077 ERROR CPSIO INV COMMAND 


65078 ERROR CPSIO NO FONT SVIT 


65079 ERROR ENTRY IS CALLGATE 


Description 


The DLL procedure ordinal number 
refers to the call gate. 


Presenta+ion Manager error codes 


Table 8-2 contains a complete list of all the common Presentation 
Manager error codes. These error codes affect both the WIN and GPI 
functions as well as most of the other Presentation Manager specific 
function. They do not affect standard C functions or the messages 
associated with the WIN and GPI functions. In addition, most of these 
errors will not affect any object-oriented features of the compiler. 
Refer to your vendor documentation to obtain a complete list of 
common C and C++ function error codes. 


Presentation Manager function error code summary 


Code Definition 


OxOOOO PMERR OK 


0xl001 PMERR INVALID HWND 


0xl002 PMERR_INVALID_HMQ 


0xl003 PMERR PARAMETER OUT OF RANGE 


0xl004 PMERR WINDOW LOCK UNDERFLOW 


0xl005 PMERR WINDOW LOCK OVERFLOW 


0xl006 PMERR BAD VVINDOW LOCK COUNT 


0xl007 PMERR WINDOW NOT LOCKED 


0xl008 PMERR INVALID SELECTOR 


0xl009 PMERR CALL FROM WRONG 


THREAD 


0xl00A PMERR RESOURCE NOT FOUND 


0xl00B PMERR INVALID STRING PARM 


0xl00C PMERR INVALID HHEAP 


Description 


There was no error, the function 
returned successfully. 


The process specified an invalid 
window handle. 


The process specified an invalid 
message queue handle. 


The parameter value is out of range 
(exceeds its defined limit). 
The process attempted to set the 
window use count below zero. 


The window use count overflowed. 


The window use count is invalid. 


The window specified in 
WINsendMsg was not locked. 


The process attempted to pass an 
invalid selector. 


OS/2 could not find the specified 
resource identity. 


The string parameter is invalid. 


The process specified an invalid 
heap handle. 


C ode D efinition 


Oxl00D PMERR INVALID HEAP POINTER 


0xl00E PMERR INVALID HEAP SIZE PARM 


0xl00F PMERR INVALID HEAP SIZE 


0xl010 PMERR INVALID HEAP SIZE WORD 


0xl011 PMERR HEAP OUT OF MEMORY 


Oxl012 PMERR HEAP MAX SIZE REACHED 


0xl013 PMERR INVALID HATOMTBL 


0xl014 PMERR INVALID ATOM 


0xl015 PMERR INVALID ATOM NAME 


0xl016 PMERR INVALID INTEGER ATOM 


0xl017 PMERR ATOM NAME NOT FOUND 


0xl018 PMERR_QUEUE_TOO_IARGE 


0xl019 PMERR INVALID FLAG 


Oxl01A PMERR INVALID HACCEL 


0xl01B PMERR INVALID HPTR 


0xl01C PMERR INVALID HENUM 


0xl01D PMERR INVALID SRC CODEPAGE 


0xl01E PMERR INVALID DST CODEPAGE 


Description 


OS/2 found an invalid heap pointer. 


OS/2 found invalid data within the 
heap. 


OS/2 found invalid data within the 
heap. 


OS/2 found invalid data within the 
heap. 


An attempt to increase the heap size 
failed. This usually occurs due to lack 
of available memory. 


You cannot increase the heap size 
beyond the maximum size of 64K. 


The process specified an invalid 
atom table handle. 


The specified atom does not exist in 
the atom table. 


The process attempted to pass an 
invalid atom name string. 


The specified atom is not a valid 
integer atom. 


The specified atom name is not in 
the atom table. 


The requested queue size is too 
large. 


The process set an invalid bit for a 
parameter. Always use predefined 
constants to avoid setting reserved 
bits. 


The process specified an invalid 
accelerator table handle. 


The process specified an invalid 
pointer handle. 


The process specified an invalid 
enumeration handle. 


The source code page parameter is 
invalid. 


The destination code page 
parameter is invalid. 


Table B-2 Continued 


Code Definition 


Oxl01f PMERR UNKNOWN COMPONENT ID 


0xl020 PMERR UNKNOWN ERROR CODE 


0xl021 PMERR SEVERITY LEVELS 


0xl034 PMERR INVALID RESOURCE FORMAT 


0xl035 WINDBG WINDOW UNLOCK WAIT 


0xl036 PMERR_NO_MSG_QUEUE 


0xl037 PMERR WIN DEBUGMSG 


0xl038 PMERR_QUEUE_FULL 


0xl039 PMERR LIBRARY LOAD FAILED 


0xl03A PMERR PROCEDURE LOAD FAILED 


0xl03B PMERR LIBRARY DELETE FAILED 


0xl03C PMERR PROCEDURE DELETE FAILED 


0xl03D PMERR ARRAY TOO LARGE 


0xl03E PMERR ARRAY TOO SMALL 


0xl03F PMERR DATATYPE ENTRY BAD 


INDE_X 


0xl040 PMERR DATATYPE ENTRY CTL BAD 


0xl041 PMERR DATATYPE ENTRY CTL MISS 


0xl042 PMERR DATATYPE ENTRY INVALID 


0xl043 PMERR DATATYPE ENTRY NOT NUM 


0xl044 PMERR DATATYPE ENTRY NOT OFF 


0xl045 PMERR DATATYPE INVALID 


Description 


Unknown component identifier. 


Unknown error code. 


OS/2 does not recognize the 
resource format. 


Your application failed to create a 
message queue to handle messages. 


The specified queue is full. 


OS/2 could not load the specified 
dynamic link library (DLL). 
OS/2 could not load the requested 
procedure. 
OS/2 could not delete the specified 
dynamic link library (DLL). 


OS/2 could not delete the requested 
procedure. 
The array is too large. 


The array is too small. 


Invalid datatype entry index. 


Invalid datatype entry control. 


The process did not provide a data 
type entry control. 
The process did not provide a valid 
datatype entry. 


The process did not provide a 
numeric datatype entry. 


The process did not provide an 
offset datatype entry. 


The process provided an invalid 
datatype. 


Code D efinition 


Oxl046 PMERR DATATYPE_NOT_UNIQUE 


0xl047 PMERR DATATYPE TOO LONG 


0xl048 PMERR DATATYPE TOO SMALL 


0xl049 PMERR DIRECTION INVALID 


0xl04A PMERR INVALID HAB 


0xl04D PMERR INVALID HSTRUCT 


0xl04E PMERR LENGTH TOO SMALL 


Oxl04F PMERR MSGID TOO SMALL 


0xl050 PMERR NO HANDLE ALLOC 


0xl051 PMERR NOT IN A PM SESSION 


Oxl052 PMERR MSG_QUEUE_ALREADY_ 


EXISFs 


Oxl055 PMERR OLD RESOURCE 


0xll01 PMERR INVALID PIB 


0xll02 PMERR INSUFF SPACE TO ADD 


Oxll03 PMERR INVALID GROUP HANDLE 


0xll04 PMERR DUPLICATE TITLE 


Oxll05 PMERR INVALID TITLE 


0xll06 PMERR INVALID TARGET HANDLE 


0xll07 PMERR HANDLE NOT IN GROUP 


0xll08 PMERR INVALID PATH STATEMENT 


Description 


The process must provide a unique 
datatype. 


The datatype is too large. 


The datatype is too small. 


The process specified an invalid 
anchor block handle. 


The process specified an invalid 
(NULL) structure handle. 
The process passed a parameter 
that did not contain enough 
information. 


The process specified a message 
identifier that is too small. 


The process attempted to access a 
PM-only function even though it is 
not operating in a PM session. 


The message queue already exists. 


The process passed an invalid PIB. 


OS/2 could not extend the 
initialization file to add the required 
program or group. This might 
indicate a disk full condition. 


The process specified an invalid 
program group handle. 
The program title that was specified 
in the PIBSTRUCT already exists 
within the same group. 


The program or group title is too 
long or contains invalid characters. 


The process specified an invalid 
program group handle. 


The process passed an invalid path 
statement. 


Table B-2 Continued 


Code D efinition 


Oxll09 PMERR NO PROGRAM FOUND 


0xll0A PMERR INVALID BUFFER SIZE 


0xll0B PMERR BUFFER TOO SMALL 


0xll0C PMERR PL INITIALISATION FAIL 


0xll0D PMERR CANT DESTROY SYS GROUP 


0xll0E PMERR INVALID TYPE CHANGE 


0xll0F PMERR INVALID PROGRAM HANDLE 


0xlll0 PMERR NOT CURRENT PL VERSION 


0xllll PMERR INVALID CIRCULAR REF 


0xlll2 PMERR MEMORY ALLOCATION ERR 


0xlll3 PMERR MEMORY DEALLOCATION 


ERR 


0xlll4 PMERR TASK HEADER TOO BIG 


0xlll5 PMERR INVALID INI FILE HANDLE 


0xlll6 PMERR MEMORY SHARE 


0xlll7 PMERR_OPEN_QUEUE 


Oxlll8 PMERR_CREATE_QUEUE 


Oxlll9 PMERR_WRITE_QUEUE 


0xlllA PMERR READ_QUEUE 


0xlllB PMERR CALL NOT EXECUTED 


0xlllc PMERR UNKNOWN APIPKT 


Description 


OS/2 could not find the specified 
Program. 


The specified buffer size is invalid. 


The buffer cannot hold the return 
data. 


The data type change is invalid. 


The process specified an invalid 
program handle. 
OS/2 found an unexpected data 
format in the initialization file. 


An error occurred during memory 
management. 


An error occurred during memory 
management. 


The task header is too big. 


The process specified an invalid 
initialization file handle. 


An error occurred during memory 
management. 


OS/2 could not open the queue. 
This usually occurs due to a lack of 
memory. 


OS/2 could not create the queue. 
This usually occurs due to a lack of 
memory. 


OS/2 experienced an error while 
writing to the queue. 


OS/2 could not read from the 
specified queue. 


Code D efinition 


OxlllD PMERR INITHREAD EXISTS 


0xlllE PMERR CREATE THREAD 


0xlllF PMERR NO HK PROFILE INSTALLED 


0xll20 PMERR INVALID DIRECTORY 


0xll21 PMERR WILDCARD IN FILENAME 


0xll22 PMERR FILENAME BUFFER FULL 


0xll23 PMERR FILENAME TOO LONG 


0xll24 PMERR INI FILE IS SYS OR USER 


0xll25 PMERR BROADCAST PLMSG 


0xll26 PMERR 190 INIT DONE 


0xll27 PMERR HMOD FOR PMSHAPI 


0xll28 PMERR SET HK PROFILE 


0xll29 PMERR API NOT ALLOWED 


0xll2A PMERR INI STILL OPEN 


0xll2B PMERR PROGDETAILS NOT IN INI 


Oxll2C PMERR PIBSTRUCT NOT IN INI 


0xll2D PMERR INVALID DISKPROGDETAILS 


0xll2E PMERR PROGDETAILS READ 


EAILORE 


0xll2F PMERR PROGDETAILS WRITE 


FAILORE 


0xll30 PMERR PROGDEIAILS_QSIZE 


FAILORE 


0xll31 PMERR INVALID PROGDETAILS 


0xll32 PMERR SHEPROFILEHOOK NOT 


FOUND 


0xll33 PMERR 190PLCONVERTED 


Description 


The destination code page 
parameter is invalid. 
The specified function does not 
support wildcards in the filename. 


The filename buffer is full. 


The filename does not conform to 
the 8,3 format for DOS disks. 


OS/2 cannot close the user or 
system initialization file. 


The initialization file still is open. 


The initialization file does not 
contain the requested program 
details. 


OS/2 detected invalid program 
details in the initialization file. 


OS/2 could not read the program 
details from the initialization file. 


OS/2 could not write the program 
details to the initialization file. 


The specified queue was too small to 
hold the program details. 


OS/2 detected invalid program 
details in the initialization file. 


Table B-2 Continued 


Code Definition 


Oxll34 PMERR FAILED TO CONVERT INI PL 


0xll35 PMERR PMSHAPI NOT INITIALISED 


0xll36 PMERR INVALID SHELL API 


HOO_K ID 


0xl200 PMERR DOS ERROR 


Oxl201 PMERR NO SPACE 


Oxl202 PMERR INVALID SVVITCH HANDLE 


0xl203 PMERR NO HANDLE 


0xl204 PMERR INVALID PROCESS ID 


0xl205 PMERR NOT SHELL 


0xl206 PMERR INVALID WINDOW 


0xl207 PMERR INVALID POST MSG 


0xl208 PMERR INVALID PARAMETERS 


0xl209 PMERR INVALID PROGRAM TYPE 


0xl20A PMERR NOT EXTENDED FOCUS 


0xl20B PMERR INVALID SESSION ID 


Oxl20C PMERR SMG INVALID ICON FILE 


0xl20D PMERR SMG ICON NOT CREATED 


Description 


The DOS call returned an error. 
Refer to Table 8-1 for a list of DOS 
call error codes. 


OS/2 reached the limit of Window 
List entries while using the 
WINAddswitchEntry function. 


The process specified an invalid 
Window List entry handle. 


The calling process did not supply a 
handle. 


The process passed an invalid 
process identifier (PID). 
The requesting process is not the 
shell. 


The process provided an invalid 
frame window in a Window List call. 


The process attempted to post an 
invalid message. 


The process passed one or more 
parameters with invalid data. 
OS/2 does not recognize the 
program type. 


The process passed an invalid 
session identifier. You must pass a 
value of 0 (for the application's own 
session) or the valid identifier of 
another session. 


The system manager could not use 
the specified icon file. 


The system manager icon was not 
created. 


Code D efinition 


Oxl20E PMERR SHL DEBUG 


0xl301 PMERR OPENING INI FILE 


Oxl302 PMERR INI FILE CORRUPT 


0xl303 PMERR INVALID PARM 


0xl304 PMERR NOT IN IDX 


Oxl305 PMERR NO ENTRIES IN GROUP 


0xl306 PMERR INI WRITE FAIL 


0xl307 PMERR IDX FULL 


0xl308 PMERR INI PROTECTED 


0xl309 PMERR MEMORY ALLOC 


0xl30A PMERR INI INIT ALREADY DONE 


0xl30B PMERR INVALID INTEGER 


0xl30C PMERR INVALID ASCIIZ 


°XL 3°D :rMPE#EESAVNA-L¥8ZEFOANLLR-ipE°c?EE;R 


Oxl401 PMERR WARNING VVINDOW NOT 


KILLED 


0xl402 PMERR ERROR INVALID WINDOW 


0xl403 PMERR ALREADY INITIALISED 


0xl405 PMERR MSG PROG NO MOU 


Oxl406 PMERR MSG PROG NON RECOV 


0xl407 PMERR VVINCONV INVALID PATH 


Description 


OS/2 could not open the 
initialization file. This usually occurs 
due to a lack of disk space. 


The initialization file is corrupt. 


The process passed a parameter 
with invalid data. 


OS/2 could not find the application 
name, key name, or program 
handle. 


There are no group entries. 


OS/2 experienced an error writing 
the initialization file. 


OS/2 cannot update a read-only 
initialization file. 


An error occurred during memory 
management. 


The specified parameter is not a 
valid integer. 


The profile string is not a valid zero- 
terminated string. 


An error occurred when the process 
tried to call the spooler validation 
routine. This error does not occur 
when the spooler is not installed. 


OS/2 experienced an error while 
attempting to kill a window. 


The specified window is invalid. 


There is no mouse attached to this 
machine, the device driver failed to 
load, or the mouse experienced a 
failure. 


Nonrecoverable application error. 
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C ode D efinition 


Oxl408 PMERR PI NOT INITIALISED 


0xl409 PMERR PL NOT INITIALISED 


0xl40A PMERR NO TASK MANAGER 


0xl40B PMERR SAVE NOT IN PROGRESS 


0xl40C PMERR NO STACK SPACE 


0xl40d PMERR INVALID COLR FIELD 


0xl40e PMERR INVALID COLR VALUE 


0xl40f PMERR COLR WRITE 


0xl501 PMERR TARGET FILE EXISTS 


0xl502 PMERR SOURCE SAME AS TARGET 


0xl503 PMERR SOURCE FILE NOT FOUND 


0xl504 PMERR INVALID NEW PATH 


0xl505 PMERR TARGET FILE NOT FOUND 


0xl506 PMERR INVALID DRIVE NUMBER 


0xl507 PMERR NAME TOO LONG 


0xl508 PMERR NOT ENOUGH ROOM ON 


DISK- 


Oxl509 PMERR NOT ENOUGH MEM 


0xl50B PMERR LOG DRV DOES NOT EXIST 


0xl50C PMERR INVALID DRIVE 


0xl50D PMERR ACCESS DENIED 


0xl50E PMERR NO FIRST SIASH 


0xl50F PMERR READ ONLY FILE 


0xl51F PMERR GROUP PROTECTED 


Description 


The task manager is missing. 


There currently is no save in 
progress. 
There is no stack space available. 


The color field is invalid. 


The color value is invalid. 


OS/2 could not overwrite the 
specified target file. 


The direct manipulation source and 
target process are the same. 


OS/2 could not find the specified 
source file. 


The new path does not exist. 


OS/2 could not find the specified 
target file. 


The specified drive does not exist. 


The name string is too long. 


There is not enough disk storage 
space to complete the operation. 


There is not enough memory to 
complete the operation. 


The specified logical drive does not 
exist. 


The specified drive does not exist. 


The process did not allocate the 
memory block properly. 


The process attempted to write to a 
read-only file. 


Code D efinition 


Oxl52F PMERR INVALID PROGRAM 


GATE-GORY 


0xl530 PMERR INVALID APPL 


Oxl531 PMERR CANNOT START 


0xl532 PMERR STARTED IN BACKGROUND 


0xl533 PMERR INVALID HAPP 


Oxl534 PMERR CANNOT STOP 


0xl601 PMERR INTERNAL ERROR 1 


Oxl602 PMERR INTERNAL ERROR 2 


Oxl603 PMERR INTERNAL ERROR 3 


Oxl604 PMERR INTERNAL ERROR 4 


Oxl605 PMERR INTERNAL ERROR 5 


Oxl606 PMERR INTERNAL ERROR 6 


Description 


The process attempted to start an 
application with a type not 
recognized by the operating system. 


You cannot start the session. 


The application started a new 
process in the background. 
The application handle passed to 
WINTerminateApp does not 
correspond to a valid session. 


You cannot stop the session. 


This is a Presentation Manager 
internal error. It usually indicates that 
a function failed due to 
circumstances outside application 
control. 


This is a Presentation Manager 
internal error. It usually indicates that 
a function failed due to 
circumstances outside application 
control. 


This is a Presentation Manager 
internal error. It usually indicates that 
a function failed due to 
circumstances outside application 
control. 


This is a Presentation Manager 
internal error. It usually indicates that 
a function failed due to 
circumstances outside application 
control. 


This is a Presentation Manager 
internal error. It usually indicates that 
a function failed due to 
circumstances outside application 
control. 


This is a Presentation Manager 
internal error. It usually indicates that 
a function failed due to 
circumstances outside application 
control. 
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Code Definition 


Oxl607 PMERR INTERNAL ERROR 7 


Oxl608 PMERR INTERNAL ERROR 8 


Oxl609 PMERE INTERNAL ERROR 9 


Oxl60A PMERR INTERNAL ERROR 10 


Oxl60B PMERR INTERNAL ERROR 11 


Oxl60C PMERR INTERNAL ERROR 12 


Oxl60D PMERE INTERNAL ERROR 13 


oxl6oE pMEFm INTEENAL ERROR 14 


Oxl60F PMERR INTEENAL EREOR 15 


Oxl610 PMERR INTERNAL ERROR 16 


Description 


This is a Presentation Manager 
internal error. It usually indicates that 
a function failed due to circumstances 
outside application control. 


This is a Presentation Manager 
internal error. It usually indicates that 
a function failed due to circumstances 
outside application control. 


This is a Presentation Manager 
internal error. It usually indicates that 
a function failed due to circumstances 
outside application control. 


This is a Presentation Manager 
internal error. It usually indicates that 
a function failed due to circumstances 
outside application control. 


This is a Presentation Manager 
internal error. It usually indicates that 
a function failed due to circumstances 
outside application control. 


This is a Presentation Manager 
internal error. It usually indicates that 
a function failed due to circumstances 
outside application control. 


This is a Presentation Manager 
internal error. It usually indicates that 
a function failed due to circumstances 
outside application control. 


This is a Presentation Manager 
internal error. It usually indicates that 
a function failed due to circumstances 
outside application control. 


This is a Presentation Manager 
internal error. It usually indicates that 
a function failed due to circumstances 
outside application control. 


This is a Presentation Manager 
internal error. It usually indicates that 
a function failed due to circumstances 
outside application control. 


Code D efinition 


Oxl611 PMERR INTERNAL EREOR 17 


Oxl612 PMERR INTERNAL ERROR 18 


Oxl613 PMERR INTEENAL ERROR 19 


Oxl614 PMERR INTEENAL ERROR 20 


Oxl615 PMERR INTERNAL ERROR 21 


Oxl616 PMERE INTERNAL ERROR 22 


Oxl617 PMERR INTERNAL ERROR 23 


Oxl618 PMERR INTERNAL ERROR 24 


Oxl619 PMERE INTERNAL EREOR 25 


Oxl61A PMERR INTERNAL ERROR 26 


Oxl61B PMERE INTERNAL ERROR 27 


Description 


This is a Presentation Manager 
internal error. It usually indicates that 
a function failed due to circumstances 
outside application control. 


This is a Presentation Manager 
internal error. It usually indicates that 
a function failed due to circumstances 
outside application control. 


This is a Presentation Manager 
internal error. It usually indicates that 
a function failed due to circumstances 
outside application control. 


This is a Presentation Manager 
internal error. It usually indicates that 
a function failed due to circumstances 
outside application control. 


This is a Presentation Manager 
internal error. It usually indicates that 
a function failed due to circumstances 
outside application control. 


This is a Presentation Manager 
internal error. It usually indicates that 
a function failed due to circumstances 
outside application control. 


This is a Presentation Manager 
internal error. It usually indicates that 
a function failed due to circumstances 
outside application control. 


This is a Presentation Manager 
internal error. It usually indicates that 
a function failed due to circumstances 
outside application control. 


This is a Presentation Manager 
internal error. It usually indicates that 
a function failed due to circumstances 
outside application control. 


This is a Presentation Manager 
internal error. It usually indicates that 
a function failed due to circumstances 
outside application control. 


This is a Presentation Manager 
internal error. It usually indicates that 
a function failed due to circumstances 
outside application control. 
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C ode D efinition 


Oxl61C PMERR INTERNAL ERROR 28 


Oxl61D PMERR INTERNAL ERROR 29 


Oxl630 PMERR INVALID FREE MESSAGE ID 


Oxl641 PMERR FUNCTION NOT SUPPORTED 


0xl642 PMERR INVALID ARRAY COUNT 


0xl643 PMERR INVALID LENGTH 


oxl644 PMERR INVALID BUNDLE rvpE 


0xl645 PMERR INVALID PARAMETER 


Oxl646 PMERR INVALID NUMBER OF PARMS 


0xl647 PMERR GREATER THAN 64K 


0xl648 PMERR INVALID PARAMETER TYPE 


0xl649 PMERR NEGATIVE STRCOND DIM 


0xl64A PMERR INVALID NUMBER OF TYPES 


0xl64B PMERR INCORRECT HSTRUCT 


Description 


This is a Presentation Manager 
internal error. It usually indicates that 
a function failed due to circumstances 
outside application control. 


This is a Presentation Manager 
internal error. It usually indicates that 
a function failed due to circumstances 
outside application control. 


The process specified an invalid 
message identifier. OS/2 assumed 
the message parameter types are 
ULONG to complete the call. 


OS/2 does not support this function. 


The array count is invalid; it is less 
than or equal to zero. 


The parameter length is invalid. 


The process attempted to pass an 
invalid bundle type. 


The parameter value is invalid for its 
converted PM type. For example, you 
cannot convert a 4-dyte value outside 
the range of -32,768 to +32,767 to 
a SHORT integer or a negative 
number to a ULONG or USHORT. 


The number of parameters is invalid. 


The size of a data item or an array 
dimension exceeds 65,535 bytes. 


The parameter type is invalid for a 
bundle mask. 


The process passed a negative array 
dimension as the data type length. 


The function call has an invalid 
number (zero) of types. 


The process provided a non-NULL 
structure handle that is invalid for 
one of the following reasons: it is 
not a data structure handle, it is the 
handle of an ERRINFO structure 


Code D efinition 


Oxl64C PMERR INVALID ARRAY SIZE 


0xl64D PMERR INVALID CONTROL 


DATATfaE 


0xl64E PMERR INCOMPLETE_CONTROL_SEQ 


Oxi64F PMERR INVALID DATArvpE 


0xl650 PMERR INCORRECT DATATYPE 


0xl651 PMERR NOT SELF DESCRIBING 


DrvF 


0xl652 PMERR_INVALID_CTRL_SEQ_INDEX or 


PMERR INVALID_CONTROL_SEQ_ 


INDE_X 


0xl653 PMERR INVALID TYPE FOR LENGTH 


0xl654 PMERR INVALID TYPE FOR OFFSET 


0xl655 PMERR INVALID TYPE FOR MPARAM 


Oxl656 PMERR INVALID MESSAGE ID 


0xl657 PMERR C LENGTH TOO SMALL 


Oxl658 PMERR APPL STRUCTURE TOO 


SMAEL 


0xl659 PMERR INVALID ERRORINFO 


HANDLE 


Description 


that it should not use on this call, or 
the process used a handle block 
returned by the bindings to the 
application for an in-line structure 
handle. 


The control data type array size is 
invalid. 


The process specified an invalid 
control data type. 


The control data type sequence is 
incomplete. 


The process specified an invalid data 
type. 


The process specified a data type 
that is incorrect for this function. 


The data type is not self-describing. 


The parameter contains an invalid 
index in the control data type 
sequence. The index points to a 
nonexistent or nonnumeric entry. 


The data type for a control length is 
invalid. 


The data type for a control offset is 
invalid. 


The message parameter type for a 
control MPARAM is invalid. You must 
use mparaml, mparam2, or mreply. 


The message identifier is invalid. 


The maximum length of the C 
structure is less than the total length 
required for the C component types. 


The application buffer supplied by 
the process was smaller than the 
length required to complete the call. 


The ERRINFO parameter is not the 
handle of an ERRINFO structure 
created by the WINGetErrorlnfo 
function. This error usually occurs 
during a WINFreeErrorlnfo call. 
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Code D efinition 


Oxl65A PMERR INVALID CHARACTER INDEX 


Ox2001 PMERR ALREADY IN AREA 


Ox2002 PMERR ALREADY IN ELEMENT 


Ox2003 PMERR ALREADY IN PATH 


Ox2004 PMERR ALREADY IN SEG 


Ox2005 PMERR AREA INCOMPLETE 


Ox2006 PMERR BASE ERROR 


Description 


The character index is invalid during 
a WINNextchar or WINprevchar 
call. It is always equal to 1 or the 
string length + 1. 
The process attempted to begin a 
new area even though an existing 
area bracket was open. 
The process attempted to begin a 
new element even though an 
existing element bracket was open. 
The process attempted to begin a 
new path even though an existing 
path bracket was open. 
The process attempted to begin a 
new segment even though an 
existing segment bracket was open. 
This error occurs during one of 
three circumstances: the process 
opened, closed, or drew a segment. 
It issued the GPIAssociate function 
while an area bracket was opened. 
A drawn segment opened an area 
bracket and ended without closing it. 
An OS/2 base error occurred. You 
can access the error using the 
OffBinaryData field of the ERRINFO 
structure returned by the 
WINGetErrorlnfo function. 


Ox2007 PMERR BITBLT LENGTH EXCEEDED The process exceeded the maximum 


BitBlt length. 


Ox2008 PMERR BITMAP IN USE 


Ox2009 PMERR BITMAP IS SELECTED 


The process tried to set a bitmap into 
a device context using GPIsetBitMap 
when it already was selected into an 
existing device context. This error also 
occurs if the process attempts to tag a 
bitmap with a local pattern set 
identifier (setid) using GPIsetBitMaplD 
when it already was tagged with an 
existing setid. 
The process attempted to delete a 
bitmap when it was selected into a 
device context. 


Code D efinition 


Ox200A PMERR BITMAP NOT FOUND 


0x200B PMERE BITMAP NOT SELECTED 


Ox200C PMERR BOUNDS OVERFLOW 


Ox200D PMERR CALLED SEG IS CHAINED 


0x200E PMERR CALLED SEG IS CURREivT 


0x200F PMERR CALLED SEG NOT FOUND 


0x2010 PMERR CANNOT DELETE ALL DATA 


0x2011 PMERR CANNOT REPIACE 


ELEM-ENT 0 


0x2012 PMERR COL TABLE NOT 


REAL-IZAB[E 


0x2013 PMERR COL TABLE NOT REALIZED 


Ox2014 PMERR COORDINATE OVERFLOW 


Ox2015 PMERR CORR FORMAT MISMATCH 


0x2016 PMERR DATA TOO LONG 


Ox2017 PMERR DC IS ASSOCIATED 


Description 


The process attempted to use a 
bitmap that does not exist. 


The process attempted to perform an 
operation on a presentation space 
associated with a memory device 
context that had no selected bitmap. 


OS/2 experienced an internal error 
during boundary data accumulation. 
This occurs if the coordinates or 
matrix transformation elements are 
invalid or too large. 


The process tried to call a segment 
with a chained attribute set. 


The process attempted to call a 
currently open segment. 


The process attempted to call a 
nonexistent segment. 


The process attempted to realize a 
color table that is not realizable. 


The process tried to realize a color 
table on a device driver that does 
not support this function. 


OS/2 experienced an internal 
coordinate overflow. This occurs if 
the coordinates or the matrix 
transformation elements are invalid 
or too large. 


The coordinate format does not 
match the anticipated format. 


The process attempted to transfer 
more than the 64,512 bytes allowed 
using GPIPutData, GPIGetData, or 
GPIElement. 


The process attempted to associate 
a presentation space with a device 
context that was already associated. 
This also occurs when the process 
attempts to destroy a device context 
without first disassociating it. 


Table B-2 Continued 


Code Definition 


Ox2018 PMERR DESC STRING TRUNCATED 


Ox2019 PMERR DEVICE DRIVER ERROR 1 


Ox201A PMERR DEVICE DRIVER ERROR 2 


Ox201B PMERR DEVICE DRIVER ERROR 3 


Ox201C PMERR DEVICE DRIVER ERROR 4 


Ox201D PMERR DEVICE DRIVER ERROR 5 


Ox201E PMERR DEVICE DRIVER ERROR 6 


Ox201F PMERR DEVICE DRIVER ERROR 7 


Ox2020 PMERR DEVICE DRIVER ERROR 8 


Ox2021 PMERR DEVICE DRIVER ERROR 9 


Description 


The process provided a description 
string with GPIBeginElement that 
exceeded the maximum permitted 
length of 251 characters. OS/2 
automatically truncated the string. 


This is a miscellaneous error number 
that OS/2 provides for user written 
device drivers. It usually does not 
have any significance. 


This is a miscellaneous error number 
that OS/2 provides for user written 
device drivers. It usually does not 
have any significance. 


This is a miscellaneous error number 
that OS/2 provides for user written 
device drivers. It usually does not 
have any significance. 


This is a miscellaneous error number 
that OS/2 provides for user written 
device drivers. It usually does not 
have any significance. 


This is a miscellaneous error number 
that OS/2 provides for user written 
device drivers. It usually does not 
have any significance. 


This is a miscellaneous error number 
that OS/2 provides for user written 
device drivers. It usually does not 
have any significance. 


This is a miscellaneous error number 
that OS/2 provides for user written 
device drivers. It usually does not 
have any significance. 


This is a miscellaneous error number 
that OS/2 provides for user written 
device drivers. It usually does not 
have any significance. 


This is a miscellaneous error number 
that OS/2 provides for user written 
device drivers. It usually does not 
have any significance. 


Code Definition 


Ox2022 PMERR DEVICE DRIVER ERROR 10 


Ox2023 PMERR DEV FUNC NOT INSTALLED 


0x2024 PMERR DOSOPEN FAILURE 


Ox2025 PMERR DOSREAD FAILURE 


Ox2026 PMERR DRIVER NOT FOUND 


Ox2027 PMERR DUP SEG 


Description 


This is a miscellaneous error number 
that OS/2 provides for user written 
device drivers. It usually does not 
have any significance. 


The presentation driver does not 
support the specified function. 


The DOSopen call did not 
successfully open the file even 
though it provided a good return 
code. This error usually happens 
during a GPILoadMetaFile or 
GPIsaveMetaFile function call. 


The DOSRead call provided a good 
return code even though it did not 
read any more bytes from the file. 
This error usually occurs when the 
file contains more bytes to read and 
could indicate a hardware failure or 
the need to use the CHKDSK utility. 


OS/2 did not find the device driver 
specified for a 
DEVPostDeviceModes function call. 


A metafile segment that the process 
wanted stored in the presentation 
space has the same segment 
identifier as an existing segment. 
This usually occurs during a 
GPIplayMetaFile call with the 
drawing mode set to draw and retain 
or retain. 


Ox2028 PMERR_DYNAMIC_SEG_SEQ_ERROR The internal state indicates that 


dynamic segment data still is visible 
after OS/2 processed all chained 
dynamic segments. The error usually 
occurs during a GPIDrawchain, 
GPIDrawForm, or GPIDrawsegment 
call processing with the removal of 
dynamic segments. This occurs if the 
process modifies or removes 
dynamically drawn segments 
(including called segments) from the 
chain while visible. 


Ox2029 PMERR DYNAMIC SEG ZERO INV 
The process attempted to open a 
dynamic segment with a segment 
identifier or zero. 


Table B-2 Continued 


C ode D efinition 


Ox202A PMERR ELEMENT INCOMPLETE 


0x202B PMERR ESC CODE NOT SUPPORTED 


Ox202C PMERR EXCEEDS MAX SEG LENGTH 


Ox202D PMERR FONT AND MODE MISMATCH 


Ox202E PMERR FONT FILE NOT LOADED 


0x202F PMERR FONT NOT LOADED 


0x2030 PMERR FONT TOO BIG 


0x2031 PMERR HARDWARE INIT FAILURE 


0x2032 PMERR HBITMAP BUSY 


Ox2033 PMERR HDC BUSY 


Ox2034 PMERR HRGN BUSY 


Ox2035 PMERR HUGE FONTS NOT 


SUPP-ORTED- 


Description 


The code the process provided for 
the DEVEscape call is not supported 
by the target device driver. 


The system exceeded the maximum 
segment size during metafile 
creation or the generation of 
retained graphics. 


The process attempted to draw 
characters using an incompatible 
character mode and character set. 
For example, the character specifies 
a vector/outline font when the mode 
calls for a image/raster font. 


The process attempted to unload a 
font file that it did not load. 


The process attempted to create a 
font that is not loaded. 


The process attempted to load a 
font that is too large. 


OS/2 detected an error while 
initializing the hardware. 


OS/2 detected an internal bitmap 
busy error. One thread locked the 
bitmap while another thread tried to 
access it. 


OS/2 detected an internal device 
context busy error. One thread 
locked the device context while 
another thread tried to access it. 


OS/2 detected an internal region 
busy error. One thread locked the 
region while another thread tried to 
access it. 


The process attempted to select a 
font larger than the 64K maximum 
size supported by the target device 
driver using the GPIsetcharset, 
GPIsetAttrs, GPIsetpatternset, or 
GPIsetMarkerset functions. 


Code Definition 


Ox2036 PMERR ID HAS NO BITMAP 


Ox2037 PMERR IMAGE INCOMPLETE 


Ox2038 PMERR INCOMPAT COLOR FORMAT 


Ox2039 PMERR INCOMPAT COLOR OPTIONS 


Ox203A PMERR INCOMPATIBLE BITMAP 


Ox203B PMERR INCOMPATIBLE METAFILE 


Ox203C PMERR INCORRECT DC TYPE 


Ox203D PMERR INSUFFICIENT DISK SPACE 


0x203E PMERR INSUFFICIENT MEMORY 


0x203F PMERR INV ANGLE PARM 


Ox2040 PMERR INV ARC CONTROL 


Description 


There is no bitmap tagged with 
the setid specified for a 
GPIQueryBitmapHandle function call. 


The process attempted to select a bit 
map or perform a BitBlt operation 
using a bit map that has a format 
incompatible with the specified 
device context. 


The process attempted to select a 
color that has a format incompatible 
with the specified device context. 


The process attempted to select a 
color option that is incompatible 
with the specified device context. 


The process attempted to select a bit 
map or perform a BitBlt operation 
using a bit map that has a format 
incompatible with the specified 
device context. 


The process attempted to associate 
a presentation space and a metafile 
that have incompatible page units, 
or size or coordinate format. This 
also can occur when the process 
attempts to play a metafile using the 
RES_RESET option (to reset the 
presentation space) to a 
presentation space associated with a 
metafile device context. 


The process attempted to perform a 
bitmap operation on a presentation 
space associated with a device 
context of a type that cannot 
support bitmap operations. 
The operation terminated due to 
insufficient disk space. 


The operation terminated due to 
insufficient memory. 


The process provided an invalid 
angle parameter with the 
GPIpartialArc function. 


The process provided an invalid 
control parameter with the 
GPIFulIArc function. 


Table B-2 Continued 


C ode Definition 


Ox2041 PMERR INV AREA CONTROL 


Ox2042 PMERR INV ARC POINTS 


Ox2043 PMERR INV AITR MODE 


Ox2044 PMERR INV BACKGROUND COL 


AITR_ 


Ox2045 PMERR INV BACKGROUND MIX 


AITR_ 


Ox2046 PMERR INV BITBLT MIX 


Ox2047 PMERR INV BITBLT STYLE 


Ox2048 PMERR INV BITMAP DIMENSION 


Ox2049 PMERR INV BOX CONTROL 


Ox204A PMERR INV BOX ROUNDING PARM 


Ox204B PMERR INV CHAR ANGLE AITR 


Description 


The process provided an invalid 
options parameter with the 
GPIBeginArea function. 


The process provided an invalid 
points parameter with the 
GPIFullArc function. 


The process provided an invalid 
mode parameter with the 
GPIsetAttrMode function. 


The process specified an invalid 
background attribute value or the 
default value with the GPIsetAttrs 
function instead of using the defaults 
mask. 


The process specified an invalid 
background attribute value or the 
default value with the GPIsetAttrs 
function instead of using the defaults 
mask. 


The process provided an invalid 
lROP parameter with the GPIBitBlt 
or GPIWCBitBlt function. 


The process provided an invalid 
options parameter with the 
GPIBitBlt or GPIWCBitBlt function. 


The process provided an invalid 
dimension with the load bitmap 
function. 


The process provided an invalid 
control parameter with the GPIBox 
function. 


The process provided an invalid 
corner rounding control parameter 
with the GPIBox function. 


The process set the default character 
angle attribute using the GPIsetAttr 
function instead of using the defaults 
mask. 


C ode D efinition 


Ox204C PMERR INV CHAR DIRECTION AITR 


Ox204D PMERR INV CHAR MODE AITR 


Ox204E PMERR INV CHAR POS OPTIONS 


Ox204F PMERR INV CHAR SET ATTR 


Ox2050 PMERR INV CHAR SHEAR ATTR 


Ox2051 PMERR INV CLIP PATH OPTIONS 


Ox2052 PMERR INV CODEPAGE 


Ox2053 PMERR INV COLOR AITR 


Ox2054 PMERR INV COLOR DATA 


Ox2055 PMERR INV COLOR FORMAT 


Ox2056 PMERR INV COLOR INDEX 


Description 


The process set the default character 
direction attribute using the 
GPIsetAttr function instead of using 
the defaults mask. 


The process set the default character 
mode attribute using the GPIsetAttr 
function instead of using the defaults 
mask. 


The process provided an invalid 
options parameter with the 
GPIcharstringpos or 
GPIcharstringposAt function. 


The process provided an invalid 
character setid attribute or set the 
default value using the GPIsetAttrs 
function instead of using the defaults 
mask. 


The process set the default character 
shear attribute using the GPIsetAttr 
function instead of using the defaults 
mask. 


The process provided an invalid 
options parameter with the 
GPIsetclippath function. 


The process provided an invalid 
codepage parameter with the 
GPIsetcp function. 


The process supplied an invalid 
color attribute value or set the 
default attribute value using 
GPIsetAttrs instead of using the 
defaults mask. 


The process provided invalid color 
table definition data with the 
GPIcreateLogcolorTable function. 


The process provided an invalid 
format parameter with the 
GPIcreateLogcolorTable function. 


The process provided an invalid 
color index parameter with the 
GPIQueryRGBColor function. 


Table a-2 
Continued 


Code Definition 


Ox2057 PMERR INV COLOR OPTIONS 


Ox2058 PMERR INV COLOR START INDEX 


Ox2059 PMERR INV COORD OFFSET 


0x205A PMERR INV COORD SPACE 


Ox205B PMERR INV COORDINATE 


0x205C PMERR INV CORRELATE DEPTH 


Ox205D PMERR INV CORREIATE TYPE 


Ox205E PMERR INV CURSOR BITMAP 


Ox205F PMERR INV DC DATA 


Ox2060 PMERR INV DC TYPE 


Ox2061 PMERR INV DEVICE NAME 


Description 


The process provided invalid color 
options parameter with the logical 
color table or color query function. 


The process provided an invalid 
starting index parameter with the 
logical color table or color query 
function. 


The process provided an invalid 
coordinate offset value. 


The process provided an invalid 
source or target coordinate space 
parameter with the GPIConvert 
function. 


The process provided an invalid 
coordinate value. 


The process provided an invalid 
maxdepth parameter with the 
GPICorrelatesegment, 
GPICorrelateFrom, or 
GPICorrelatechain function. 


The process provided an invalid type 
parameter with the 
GPICorrelatesegment, 
GPICorrelateFrom, or 
GPICorrelatechain function. 


The process provided an invalid 
pointer with the WINsetpointer 
function. 


The process provided an invalid data 
parameter with the DEVopenDC 
function. 


The process provided an invalid type 
parameter with the DEVopenDC 
function, or it issued a function that 
is invalid for a OD METAFILE 
NOQUERY device-context. 


The process provided an invalid 
devicename parameter with the 
DEVPostDeviceModes function. 


C ode D efinition 


Ox2062 PMERR INV DEV MODES OPTIONS 


Ox2063 PMERR INV DRAW CONTROL 


Ox2064 PMERR INV DRAW VALUE 


Ox2065 PMERR INV DRAWING MODE 


Ox2066 PMERR INV DRIVER DATA 


0x2067 PMERR INV DRIVER NAME 


0x2068 PMERR INV DRAW BORDER OPTION 


Ox2069 PMERR INV EDIT MODE 


Ox206A PMERR INV ELEMENT OFFSET 


Ox206B PMERR INV ELEMENT POINTER 


Ox206C PMERR INV END PATH OPTIONS 


Ox206D PMERR INV ESC CODE 


Ox206E PMERR INV ESCAPE DATA 


Ox206F PMERR INV EXTENDED LCID 


Description 


The process provided an invalid 
options parameter with the 
DEVPostDeviceModes function. 


The process specified an invalid 
control parameter with the 
GPIsetDrawcontrol function. 


The process specified an invalid 
value parameter with the 
GPIsetDrawcontrol function. 


The process specified an invalid 
mode parameter with the 
GPIsetDrawcontrol function with 
draw and retain or draw set. 


The process specified invalid driver 
data. 


The process specified an uninstalled 
device driver name. 


The process specified an invalid 
option parameter with the 
WINDrawBorder function. 


The process provided an invalid 
mode parameter with the 
GPIsetEditMode function. 


The process provided an invalid 
offset parameter with the 
GPIQueryElement function. 


The process attempted to issue a 
GPIPutData call without setting the 
element pointer to point at the last 
element. 


The process attempted to create or 
delete a path out of context of the 
path bracket. 
The process provided an invalid 
code parameter with the 
DEVEscape function. 


The process provided an invalid data 
parameter with the DEVEscape 
function. 


The process specified an invalid 
local identifier. 


Table B -2 Continued 


C ode D efinition 


Ox2070 PMERR INV FILL PATH OPTIONS 


Ox2071 PMERR INV FIRST CHAR 


Ox2072 PMERR INV FONT AITRS 


Ox2073 PMERR INV FONT FILE DATA 


Ox2074 PMERR INV FOR THIS DC TYPE 


Ox2075 PMERR INV FORMAT CONTROL 


0x2076 PMERR INV FORMS CODE 


Ox2077 PMERR INV FONTDEF 


Ox2078 PMERR INV GEOM LINE WIDTH 


AITR_ 


Ox2079 PMERR INV GETDATA CONTROL 


Ox207A PMERR INV GRAPHICS FIELD 


Ox207B PMERR INV HBITMAP 


0x207C PMERR INV HDC 


Description 


The process provided an invalid 
options parameter with the 
GPIFillpath function. 


The process provided an invalid 
firstchar parameter with the 
GPIQuerywidthTable function. 


The process provided an invalid 
attribute parameter with the 
GPIcreateLogFont function. 


The GPILoadFonts, 
GPILoadpublicFonts, 
GPIQueryFontFileDescriptions , or 
GPIQueryFullFontFileDescs font file 
contains invalid data. 


The process issued a 
GPIRemoveDynamics or 
GPIDrawDynamics call to a 
presentation space associated with a 
metafile device context. 


The process provided an invalid 
forms code parameter with the 
DEVQueryHardcopycaps function. 


The process specified an invalid font 
definition. 


The process specified an invalid 
geometric line width attribute value. 
The process specified an invalid 
format parameter with the 
GPIGetData function. 


The process provided an invalid field 
parameter with the 
GPIsetGraphicsField function. 


The process specified an invalid 
bitmap handle. 


The process specified an invalid 
device context handle or micro 
presentation space handle. 


Code Definition 


Ox207D PMERR INV HJOURNAL 


0x207E PMERR INV HMF 


0x207F PMERR INV HPS 


0x2080 PMERR INV HRGN 


0x2081 PMERR INV ID 


Ox2082 PMERR INV IMAGE DATA LENGTH 


Ox2083 PMERR INV IMAGE DIMENSION 


Ox2084 PMERR INV IMAGE FORMAT 


Ox2085 PMERR INV IN AREA 


Ox2086 PMERR INV IN CALLED SEG 


0x2087 PMERR INV IN CURRENT EDIT 


MOD_E 


0x2088 PMERR INV IN DRAW MODE 


Ox2089 PMERR INV IN ELEMENT 


Ox208A PMERR INV IN IMAGE 


Description 


The process specified an invalid 
metafile handle. 


The process specified an invalid 
presentation space handle. 


The process specified an invalid 
region handle. 


The process provided an invalid 
lpsid parameter with the 
GPIRestoreps function. 


The process provided an invalid 
lLength parameter with the 
GPIImage function. There is 
mismatch between the image size 
and data length (lLength). 


The process provided an invalid 
psizllmagesize parameter with the 
GPIImage function. 


The process provided an invalid 
lFormat parameter with the 
GPIImage function. 


The process attempted to issue a 
function that is invalid within an area 
bracket. You usually can detect this 
while the actual drawing mode is 
draw or draw and retain or during 
segment drawing or correlation 
functions. 


The process attempted to issue a 
function that is invalid when using 
the current editing mode. 


The process attempted to issue a 
function that is invalid in draw 
mode. 


The process attempted to issue a 
function that is invalid within an 
element bracket. 


The process attempted to issue a 
function that is invalid within an 
element bracket. 


Table B-2 Continued 


%RE£.|§```orngse` 


Code D efinition 


Ox208B PMERR INV IN PATH 


Ox208C PMERR INV IN RETAIN MODE 


Ox208D PMERR INV IN SEG 


Ox208E PMERR INV IN VECTOR SYMBOL 


Ox208F PMERR INV INFO TABLE 


Ox2090 PMERR INV JOURNAL OPTION 


0x2091 PMERR INV KERNING FLAGS 


0x2092 PMERR INV LENGTH OR COUNT 


0x2093 PMERR INV LINE END ATTR 


I 


0x2094 PMERR INV LINE JOIN AITR 


0x2095 PMERR INV LINE TYPE AITR 


Ox2096 PMERR INV LINE WIDTH ATTR 


Ox2097 PMERR INV LOGICAL ADDRESS 


0x2098 PMERR INV MARKER BOX AITR 


Description 


The process attempted to issue a 
function that is invalid within a path 
bracket. 


The process attempted to issue a 
function (for example a query) that is 
invalid when the actual drawing 
mode is not draw or draw and 
retain. 


The process attempted to issue a 
function that is invalid within a 
segment bracket. 


OS/2 detected an invalid order 
inside a vector symbol definition 
while drawing a vector (outline) font. 


The process specified an invalid 
bitmap information table with a 
bitmap operation. 


The process specified an invalid 
length or count parameter. 


The process specified an invalid line 
end attribute value. 


The process specified an invalid line 
join attribute value. 


The process specified an invalid line 
type attribute value or the default 
value using the GPIsetAttrs function 
instead of using the defaults mask. 


The process specified an invalid line 
width attribute value or the default 
value using the GPIsetAttrs function 
instead of using the defaults mask. 


The process specified an invalid 
device logical address. 


The process specified an invalid 
marker box attribute value. 


Code D efinition 


Ox2099 PMERR INV MARKER SET AITR 


Ox209A PMERR INV MARKER SYMBOL AITR 


Ox209B PMERR INV MATRIX ELEMENT 


0x209C PMERR INV MAX HITS 


Ox209D PMERR INV METAFILE 


ox2o9E PMERR Irv METAFILE LENGTH 


Ox209F PMERR INV METAFILE OFFSET 


Ox20A0 PMERR INV MICROPS DRAW 


CONTROL 


Ox20AI PMERR INV MICROPS FUNCTION 


Ox20A2 PMERR INV MICROPS ORDER 


Ox20A3 PMERR INV MIX AITR 


Description 


The process specified an invalid 
marker set attribute value or the 
default value using the GPIsetAttrs 
function instead of using the defaults 
mask. 


The process specified an invalid 
marker symbol attribute value or the 
default value using the GPIsetAttrs 
function instead of using the defaults 
mask. 


The process specified an invalid 
transformation matrix element. 


The process provided an invalid 
maxhits parameter with the 
GPICorrelatesegment, 
GPICorrelateForm, or 
GPICorrelatechain function. 


The process provided an invalid 
metafile with the GPIplayMetaFile 
function. 


The process specified 
length parameter with 
GPIsetMetaFileBits or 
GPIQueryMetaFileBits 


The process specified 
length parameter with 
GPIsetMetaFileBits or 
GPIQueryMetaFileBits 


The process provided 


an invalid 
the 


function. 


an invalid 
the 


function. 


a draw control 


parameter with GPIsetDrawcontrol 
that is invalid within a micro 
presentation space. 
The process attempted to issue a 
function that is invalid in a micro 
presentation space. 
The process attempted to play a 
metafile containing orders that are 
invalid within a micro presentation 
Space. 


The process specified an invalid mix 
attribute value or the default value 
using the GPIsetAttrs function 
instead of using the defaults mask. 


Table B-2 Continued 


Code Definition 


Ox20A4 PMERR INV MODE FOR OPEN DYN 


Ox20A5 PMERR INV MODE FOR REOPEN 


SEG 


Ox20A6 PMERR INV MODIFY PATH MODE 


Ox20A7 PMERR INV MULTIPLIER 


Ox20A8 PMERR INV NESTED FIGURES 


0x20A9 PMERR INV OR INCOMPAT OPTIONS 


Ox20RA PMERR INV ORDER LENGTH 


Ox20AB PMERR INV ORDERING PARM 


Ox20AC PMERR INV OUTSIDE DRAW MODE 


Ox20AD PMERR INV PAGE VIEWPORT 


Ox20AE PMERR INV PATH ID 


Description 


The process attempted to open a 
segment with the AITR_DYNAMIC 
segment set while the drawing mode 
was set to DM DRAW or 
DM DRAWAN-DRETAIN. 


The process attempted to reopen an 
existing segment while the draw 
mode was set to DM DRAW or 
DM DRAWANDRET-AIN. 


The process provided an invalid 
mode parameter with the 
GPIModifypath function. 


The process provided an invalid 
multiplier parameter with the 
GPIpartialArc or GPIFulIArc function. 


OS/2 detected nested figures within 
a path definition. 


The process provided an invalid or 
incompatible (with micro 
presentation space) options 
parameter with the GPIcreateps or 
GPIsetps function. 


The process provided an invalid 
order length during GPIPutData or 
segment drawing. 


The process provided an invalid 
ordering parameter with the 
GPIsetsegmentpriority function. 


The process attempted to issue a 
GPIsaveps or GPIRestoreps call or 
an output-only function (for 
example, GPIpaintRegion) from 
GPIplayMetaFile without setting the 
drawing mode to DM_DRAW. 


The process provided an invalid 
viewport parameter with the 
GPIsetpageviewport function. 


The process provided an invalid 
options parameter with the 
GPIOutlinepath function. 


Code D efinition 


Ox20AF PMERR INV PATH MODE 


0x20B0 PMERR INV PATTERN AITR 


Ox20BI PMERR INV PATTERN REF PT AITR 


0x2082 PMERR INV PATTERN SET AITR 


Ox2083 PMERR INV PATTERN SET FONT 


0x2084 PMERR IIV PICK APERTURE OFTON 


Ox2085 PMERR INV PICK APERTURE POSN 


0x2086 PMERR INV PICK APERTURE SIZE 


Ox2087 PMERR INV PICK NUMBER 


0x20B8 PMERR INV PLAY METAFILE OPTION 


Ox20B9 PMERR INV PRIMITIVE TYPE 


Ox20BA PMERR INV PS SIZE 


Ox20BB PMERR INV PUTDATA FORMAT 


Ox20BC PMERR INV_QUERY_ELEMENT_NO 


Description 


The process specified an invalid 
path identifier parameter. 
The process specified an invalid 
pattern symbol attribute value or the 
default value using the GPIsetAttrs 
function instead of using the defaults 
mask. 


The specified provided an invalid 
attribute value. 


The process specified an invalid 
pattern set attribute value or the 
default value using the GPIsetAttrs 
function instead of using the defaults 
mask. 


The process attempted to use an 
unsuitable font as a pattern set. 


The process provided an invalid 
options parameter with the 
GPIsetpickAperturesize function. 


The process specified an invalid pick 
aperture position. 


The process provided an invalid pick 
aperture size parameter with the 
GPIsetpickAperturesize function. 


The process provided an invalid 
option parameter with the 
GPIplayMetaFile function. 


The process provided an invalid 
primitive type parameter with the 
GPIsetAttrs or GPIQueryAttrs 
function. 


The process provided an invalid size 
parameter with the GPIcreateps or 
GPIsetps function. 


The process provided an invalid 
format parameter with the 
GPIPutData function. 


The process provided an invalid start 
parameter with the DEVQuerycaps 
function. 


Table B-2 Continued 


C ode D efinition 


Ox20BD PMERR INV RECT 


0x20BE PMERR INV REGION CONTROL 


Ox20BF PMERR INV REGION MIX MODE 


Ox20C0 PMERR INV REPLACE MODE FUNC 


Ox20CI PMERR INV RESEFIVED FIELD 


0x20C2 PMERR INV RESET OPTIONS 


Ox20C3 PMERR INV RGBCOLOR 


Ox20C4 PMERR INV SCAN SIART 


Ox20C5 PMERR INV SEG AITR 


Ox20C6 PMERR INV SEG AITR VALUE 


Ox20C7 PMERR INV SEG CH LENGTH 


0x20C8 PMERR INV SEG NAME 


0x20C9 PMERR INV SEG OFFSET 


Description 


The process specified an invalid 
rectangle parameter. 
The process provided an invalid 
control parameter with the 
GPIQueryRegionRects function. 
The process provided an invalid 
mode parameter with the 
GPICombineRegion function. 
The process attempted to issue a 
GPIPutData call with the editing 
mode set to SEGEM REPIACE. 
The process specified an invalid 
reserved field. 
The process provided an invalid 
options parameter with the 
GPIResetps function. 
The process provided an invalid 
RGB color parameter with the 
GPIQueryNearestcolor or 
GPIQuerycolor function. 
The process provided an invalid scan 
start parameter with a bitmap 
function. 
The process provided an invalid 
attribute parameter with the 
GPIsetsegmentAttrs, 
GPIQuerysegmentAttrs, 
GPIsetlnitialsegmentAttrs , or 
GPIQuerylnitialsegementAttrs 
function. 
The process provided an invalid 
attribute value parameter with the 
GPIsetsegmentAttrs or 
GPIsetlnitialsegmentAttrs function. 
The process specified an invalid 
chained segment length. 
The process specified an invalid 
segment identifier. 
The process provided an invalid 
offset parameter with the 
GPIPutData function. 


C ode D efinition 


Ox20CA PMERR INV SETID 


0x20CB PMERR INV SETID TYPE 


0x20CC PMERR INV SET VIEWPORT OPTION 


0x20CD PMERR INV SHARPNESS PARM 


Ox20CE PMERR INV SOURCE OFFSET 


0x20CF PMERR INV STOP DRAW VALUE 


Ox20D0 PMERR INV TRANSFORM TYPE 


Ox20DI PMERR INV USAGE PARM 


Ox20D2 PMERR INV VIEWING LIMITS 


Ox20D3 PMERR JFILE BUSY 


0x20D4 PMERR JNL FUNC DATA TOO LONG 


0x20D5 PMERR KERNING NOT SUPPORTED 


Ox20D6 PMERR LABEL NOT FOUND 


0x20D7 PMERR MATRIX OVERFLOW 


Ox20D8 PMERR METAFILE INTERNAL ERROR 


Ox20D9 PMERR METAFILE IN USE 


Description 


The process specified an invalid setid. 


The process specified an invalid 
setid type. 


The process provided an invalid 
sharpness parameter with the 
GPIPolyFilletsharp function. 


The process specified an invalid 
source offset. 


The process provided an invalid 
value parameter with the 
GPIsetstopDraw function. 


The process provided an invalid 
options parameter with the 
transform matrix function. 


The process provided an invalid 
options parameter with the 
GPIcreateBitmap function. 


The process provided an invalid 
limits parameter with the 
GPIsetviewingLimits function. 


The process requested kerning on a 
GPIcreateLogFont call to a 
presentation space associated with a 
device context that does not support 
kerning. 


The specified element label does not 
exist. 


OS/2 detected an internal overflow 
error during matrix multiplication. 
This occurs if the coordinates or 
matrix transformation elements are 
invalid or too large. 


OS/2 detected an internal 
inconsistency during metafile unlock 
processing. 
A thread tried to access a metafile in 
use by another thread. 


Table B-2 Continued 


Code D efinition 


Ox20DA PMERR METAFILE LIMIT EXCEEDED 


Ox20DB PMERR NAME SIACK FULL 
0x20DC PMERR NOT CREATED BY 


DEV6PEN5C 


Ox20DD PMERR NOT IN AREA 


Ox20DE PMERR NOT IN DRAW MODE 


Ox20DF PMERR NOT IN ELEMENT 


Ox20E0 PMERR NOT IN IMAGE 


Ox20EI PMERR NOT IN PATH 


Ox20E2 PMERR NOT IN RETAIN MODE 


Ox20E3 PMERR NOT IN SEG 


Ox20E4 PMERR NO BITMAP SELECTED 


Ox20E5 PMERR NO CURRENT ELEMENT 


Description 


The process exceeded the maximum 
permitted metafile size during 
recording. 


The name stack is full. 
The process attempted to destroy a 
device context using DEVcloseDC 
that it did not create using 
DEVopenDC. 
The process attempted to end an 
area using the GPIEndArea function 
or during segment drawing while not 
in an area bracket. 
The process attempted to issue the 
GPIsaveps or GPIRestoreps 
function while the drawing mode 
was set to DM DRAW. 
The process attempted to end an 
element using the GPIEndElement 
function or during segment drawing 
while not in an element bracket. 
The process attempted to end an 
image during segment drawing even 
though it was not in an image bracket. 
The process attempted to end a 
path using the GPIEndpath function 
or during segment drawing while not 
in a path bracket. 
The process attempted to issue a 
segment editing element function 
that is invalid when the actual 
drawing mode is not set to retain. 
The process attempted to end a 
segment using the GPIEndsegment 
function while not in a segment 
bracket. 
The process attempted to operate 
on a memory device context that 
has no bitmap selected. 
The process attempted to issue a 
GPIQueryElement or 
GPIQueryElementType call even 
though there is no open element. 


C ode D efinition 


Ox20E6 PMERR NO CURRENT SEG 


Ox20E7 PMERR NO METAFILE RECORD 


HANE)LE 


Ox20E8 PMERR ORDER TOO BIG 


Ox20E9 PMERR OTHER SET ID REFS 


Ox20EA PMERR OVERRAN SEG 


0x20EB PMERR OWN SET ID REFS 


0x20EC PMERR PATH INCOMPLETE 


Ox20ED PMERR PATH LIMIT EXCEEDED 


0x20EE PMERR PATH UNKNOWN 


Ox20EF PMERR PEL IS CLIPPED 


Ox20F0 PMERR PEL NOT AVAIIABLE 


Ox20FI PMERR PRIMITIVE STACK EMPTY 


Description 


The process attempted to issue a 
GPIQueryElement or 
GPIQueryElementType call even 
though there is no open segment. 


OS/2 could not find the metafile 
record handle during metafile 
recording, or the process did not 
issue a DEVEscape 
(DEVESC_STARTDOC) call when 
drawing to a OD_QUEUED device 
context with a pszDataType field of 
PM_Q_STD. 


OS/2 exceeded an internal size limit 
while converting orders from short 
to long format during GPIPutData 
processing. It could mean that an 
order was too long to convert. 


OS/2 could not unload the specified 
font because another process still is 
referencing the setid. 


The process attempted to open or 
close a segment either directly or 
during segment drawing. This error 
also could occur if the process issued 
a GPIAssociate while there is an 
open path bracket. 


OS/2 exceeded an internal size limit 
during path or area processing. 


The process attempted to perform a 
path function using a nonexistent 
path. 
The process attempted to query a 
clipped PEL using the GPIQuerypel 
function. 


The process attempted to query a 
pel that did not exist using the 
GPIQuerypel function. This could 
occur with a memory device context 
with no selected bitmap. 


The primitive stack is empty. 


Table B-2 Continued 


C ode D efinition 


Ox20F2 PMERR PROLOG ERROR 


0x20F3 PMERR PROLOG SEG AITR NOT SET 


Ox20F4 PMERR PS BUSY 


Ox20F5 PMERR PS IS ASSOCIATED 


Ox20F6 PMERR RAM JNL FILE TOO SMALL 


0x20F7 PMERR REALIZE NOT SUPPORTED 


Ox20F8 PMERR REGION IS CLIP REGION 


Ox20F9 PMERR RESOURCE DEPLETION 


0x20FA PMERR SEG AND REFSEG ARE 


SAME 


Ox20FB PMERR SEG CALL RECURSIVE 


0x20FC PMERR SEG CALL STACK EMPTY 


Ox20FD PMERR SEG CALL STACK FULL 


Description 


OS/2 detected a prolog error during 
drawing. It uses segment prologs 
infernally within retained segments 
and metafiles. This error also occurs 
when OS/2 issues an End Prolog 
order outside a prolog. 


The process attempted to access the 
presentation space from more than 
one thread simultaneously. 


The process attempted to destroy a 
presentation or associate a 
presentation space that still is 
associated with a device context. 


The process attempted to create a 
realizable logical color table on a 
device driver that does not support 
this function. 


The process attempted to perform a 
region operation on a region that is 
selected as a clip region. 


An internal resource depletion error 
occurred. 


The process passed the same 
identifier for the segid and refsegid 
when calling the 
GPIsetsegmentpriority function. 


OS/2 detected a recursive condition 
in a segment call. 


OS/2 detected an empty call stack 
condition while attempting to a pop 
function during GPIPop or segment 
drawing. 


OS/2 detected a stack full condition 
when attempting to call a segment 
using the GPIcallsegmentMatrix 
function, attempting to preserve an 
attribute, or during segment drawing. 


C ode D efinition 


Ox20FE PMERR SEG IS CURRENT 


Ox20FF PMERR SEG NOT CHAINED 


Ox2100 PMERR SEG NOT FOUND 


0x2101 PMERR SEG STORE LIMIT EXCEEDED 


0x2102 PMERR SETID IN USE 


Ox2103 PMERR SETID NOT FOUND 


0x2104 PMERR STARTDOC NOT ISSUED 


Ox2105 PMERR STOP DRAW OCCURRED 


Ox2106 PMERR TOO MANY METAFILES IN 


USE 


0x2107 PMERR TRUNCATED ORDER 


0x2108 PMERR UNCHAINED SEG ZERO INV 


Ox2109 PMERR UNSUPPORTED AITR 


0x210A PMERR UNSUPPORTED AITR VALUE 


0x210B PMERR ENDDOC NOT ISSUED 


Ox210C PMERR PS NOT ASSOCIATED 


Description 


The process attempted to issue a 
GPIGetData call for a currently open 
segment. 


The process attempted to issue a 
GPIDrawFrom, GPICorrelateFrom , 
or GPIQuerysegmentpriority call for 
an unchained segment. 


The specified segment identifier 
does not exist. 


The process exceeded the maximum 
permitted segment store size limit. 
The process attempted to specify a 
setid that already was in use as the 
currently selected character, marker, 
or pattern set. 


The process attempted to delete a 
nonexistent setid. 


The process attempted to request to 
write spooled output without issuing 
a STARTDOC first. 


OS/2 stopped segment drawing or 
GPIplayMetaFile prematurely in 
response to a GPIsetstopDraw 
request. 


A process exceeded the maximum 
number of metafiles. 


OS/2 detected an incomplete order 
during segment processing. 


The process attempted to open a 
segment using segment identifier 
zero and did not specify the 
ATTR CHAINED attribute. 


Unsupported attribute. 


Unsupported attribute value. 


The process attempted to close 
spooled output without first issuing 
an ENDDOC. 


The process attempted to access a 
presentation space that is not 
associated with a device context. 


Table B-2 Continued 


Code D efinition 


Ox210D PMERR INV FLOOD FILL OPTIONS 


0x210E PMERR INV FACENAME 


Ox210F PMERR PALETTE SELECTED 


Ox2110 PMERR NO PALETTE SELECTED 


Ox2111 PMERR INV HPAL 


0x2112 PMERR PALETTE BUSY 


0x2113 PMERR START POINT CLIPPED 


Ox2114 PMERR NO FILL 


Ox2115 PMERR INV FACENAMEDESC 


0x2116 PMERR INV BITMAP DATA 


Ox2ii7 PMERR Irv CHAR ALIGN AITR 


Ox2118 PMERR INV HFONT 


0x2119 PMERR HFONT IS SELECTED 


Description 


The process provided invalid flood 
fill parameters. 


The process provided an invalid font 
family name to the 
GPIQueryFacestring function. 


You cannot perform a palette 
operation in a presentation space 
while the palette is selected. 


An attempt to realize a palette failed 
because the process did not 
previously select a palette into the 
presentation space. 
The process specified an invalid 
color palette handle. 


The process attempted to reset the 
owner of a palette while it was busy. 


The specified flood file starting point 
is outside the current clipping path 
Or region. 


OS/2 did not perform a flood fill for 
one of two reasons: the starting 
point color was the same as the 
input color when the process 
requested a boundary fill, or the 
starting point color was not the 
same as the input color when the 
process requested a surface fill. 
The process provided an invalid face 
name description. 


The process provided an invalid 
bitmap. 


The process provided an invalid text 
alignment attribute with the 
GPIsetTextAlignment function. 


The process specified an invalid font 
handle. 


The process tried to change the 
owner of a font or delete it when it 
currently is selected. 


Code Definition 


Ox4001 PMERR SPL DRIVER ERROR 


Ox4002 PMERR SPL DEVICE ERROR 


0x4003 PMERR SPL DEVICE NOT INSTALLED 


0x4004 PMERR_SPL_QUEUE_ERROR 


0x4005 PMERR SPL INV HSPL 


0x4006 PMERR SPL NO DISK SPACE 


0x4007 PMERR SPL NO MEMORY 


0x4008 PMERR SPL PRINT ABORT 


0x4009 PMERR SPL SPOOLER NOT 


INSTALLE-D 


0x400A PMERR SPL INV FORMS CODE 


Ox4OOB PMERR SPL INv pRloRlrv 


Ox400C PMERR SPL NO FREE JOB ID 


0x400D PMERR SPL NO DATA 


0x400E PMERR SPL INV TOKEN 


ox4ooF PMERR SPL INv DATArvpE 


0x4010 PMERR SPL PROCESSOR ERROR 


0x4011 PMERR SPL INV JOB ID 


0x4012 PMERR SPL JOB NOT PRINTING 


0x4013 PMERR SPL JOB PRINTING 


0x4014 PMERR_SPL_QUEUE_ALREADY_ 


EXISTS 


0x4015 PMERR_SPL_INV_QUEUE_NAME 


0x4016 PMERR_SPL_QUEUE_NOT_EMPTY 


0x4017 PMERR SPL DEVICE ALREADY 


EXISFs 


Ox4018 PMERR SPL DEVICE LIMIT REACHED 


0x4019 PMERR SPL STATUS STRING TRUNC 


Description 


The spooler cannot find and the 
application has not supplied the 
specified Presentation Manager 
device driver. 


The spooler experience an error. 


The spooler device is not installed. 


No spooler queue supplied or found. 


The spooler handle is invalid. 


There is not enough free disk space. 


There is not enough free memory. 


The spooler already aborted the job. 


The spooler is not installed. 


The job form code is invalid. 


The job priority is invalid. 


There is no free job id available. 


No data supplied or found. 


The token is invalid. 


The spool file data type is invalid. 


No spooler queue processor 
supplied or found. 


The job id is invalid. 


The print job is not printing. 


The print job already is printing. 


The spooler queue already exists. 


The spooler queue name is invalid. 


The spooler queue contains print jobs. 


The specified spooler device already 
exists. 


The spooler has reached its limit on 
the number of devices. 


The spooler truncated the print job 
status string. 


Table B-2 Continued 


C ode D efinition 


Ox401A PMERR SPL INV LENGTH OR COUNT 


0x401B PMERR SPL FILE NOT FOUND 


0x401C PMERR SPL CANNOT OPEN FILE 


0x401D PMERR SPL DRIVER NOT INSTALLED 


0x401E PMERR SPL INV PROCESSOR 


DATfYPE 


0x401F PMERR SPL INV DRIVER DATATYPE 


0x4020 PMERR SPL PROCESSOR NOT INST 


0x4021 PMERR SPL NO SUCH LOG 


ADDRESS- 


Ox4022 PMERR SPL PRINTER NOT FOUND 


0x4023 PMERR SPL DD NOT FOUND 


Ox4024 PMERR_SPL_QUEUE_NOT_FOUND 


0x4025 PMERR_SPL_MANY_QUEUES_ASSOC 


0x4026 PMERR_SPL_NO_QUEUES 


ASSOCIATED 


0x4027 PMERR SPL INI FILE ERROR 


0x4028 PMERR_SPL_NO_DEFAULT_QUEUE 


0x4029 PMERR SPL NO CURRENT FORMS 


CODE 


0x402A PMERR SPL NOT AUTHORISED 


0x402B PMERR SPL TEMP NETWORK ERROR 


Description 


The length or count is invalid. 


Unable to find the specified file. 


The spooler could not open the 
specified file. 


The Presentation Manger device 
driver has not been installed. 


The data type is invalid for the 
spooler queue processor. 


The data type is not valid for a 
Presentation Manager device driver. 


There is no spool queue processor 
installed. 


The logical address does not exist. It 
is not defined within the initialization 
file. 


The spooler could not find the 
printer definition. 
The spooler could not find the 
Presentation Manager printer device 
driver definition. 


OS/2 could not find the spooler 
queue definition. 
There is more than one queue 
associated with the printer. 


There is not queue associated with 
the printer. 


The spooler experienced an error 
accessing the initialization file. 


There is no default spooler queue for 
the printer. 


The Presentation Manager device 
driver does not have a defined forms 
code. 


The calling process is not authorized 
to perform this operation. 


The spooler experienced a 
temporary network error. 


Code D efinition 


Ox402C PMERR SPL IiARD NEll^/ORK ERROR 
0x402D PMERR DEL NOT ALLOWED 
0x402E PMERR_CAN-NOT_DEL_QP_REF 


0x402F PMERR_CANNOT_DEL_QNAME_REF 


0x4030 PMERR CANNOT DEL PRINTER 


DD EEF 


0x4031 PMERR CANNOT DEL PRN NAME 


REF 


0x4032 PMERR CANNOT DEL PRN ADDR 


REF 


0x4033 PMERR_SPOOLER_QP_NOT_DEFINED 


0x4034 PMERR PRN NAME NOT DEFINED 
0x4035 PMERR PRN ADDR NOT DEFINED 
0x4036 PMERR PRINTER DD NOT DEFINED 


0x4037 PMERR_PRINTER_QUEUE_NOT_ 


DEFINED 


0x4038 PMERR PRN ADDR IN USE 


0x4039 PMERR SPL TOO MANY OPEN FILES 
0x403A PMERR_SPL_CP_NOT_REQD 


0x4040 PMERR UNABLE TO CLOSE DEVICE 


Ox5001 PMERR INV TYPE 
0x5002 PMERR INV CONV 


0x5003 PMERR INV SEGLEN 


Ox5004 PMERR DUP SEGNAME 


Ox5005 PMERE INV RTORM 


Description 


Hard network error. 
You cannot delete this object. 
You cannot delete the spooler queue 
processor due to a reference. 
You cannot delete the spooler queue 
due to a reference. 
You cannot delete the Presentation 
Manager device driver due to a 
reference. 
You cannot delete the printer due to 
a reference. 
You cannot delete the printer port 
due to a reference. 
There is no spooler queue processor 
defined. 
The printer is undefined. 
The printer port is undefined. 
There is no device driver defined for 
the printer. 
There is no spooler defined for the 
printer. 
A printer already is defined on the 
port. 
There are too many files open. 
The spooler does not require a 
codepage. 
OS/2 cannot close the print device 
due to some error (for example, the 
printer is off line). 
Invalid file type parameter. 
The process provided an invalid 
conversion-type parameter. 
The order length exceeds the 
remaining segment length in the 
input PIF. 
The process provided a called 
segment whose name matches the 
name of another called segment 
within the input PIF. 
OS/2 detected a set (default) viewing 
transform order with an inconsistent 
mask and order length in the input 
PIE. 


Table B-2 Continued 


Code Definition 


Ox5006 PMERR INV VIEWLIM 


Ox5007 PMERR INV 3DCOORD 


Ox5008 PMERR SMB OVFLOW 


Ox5009 PMERR SEG OVFLOW 


Description 


OS/2 detected a set viewing limits 
order with an inconsistent mask and 
order length in the input PIF. 
OS/2 detected an order specifying 
3-dimensional coordinates in the 
input PIF. 
The input PIE has more than 1000 
called symbol sets defined. Exceeding 
this value overflows an internal buffer. 
The input PIE has more than 1000 
called segments. Exceeding this 
value overflows an internal buffer. 


Ox5010 PMERR PIG DUP FILENAME 


The table does not provide descriptions for every error code. This 
usually occurs because the vendor documentation does not contain 
any description for the error code and no function uses it. In most 
cases, the definition column contains enough information for you 
to derive the meaning of the error within the context of the 
function that returned it. 


GPI-, WIN-, and Help 
Manager-specific error codes 


This appendix does not include the GPI or WIN manager specific 
error codes. You can find a complete listing of these codes in 
chapter 3. Each section contains a complete listing of error codes 
applicable to that particular function. If there are no error codes 
associated with a function, then you can assume it returns only the 
Presentation Manager error codes listed in this appendix or within 
the function description. 


The Help Manager error codes varied so much from vendor to 
vendor that this appendix could not adequately cover all the 
possible permutations. Refer to your vendor documentation for 
a complete list of Help Manager specific calls. 


EEEE}EE}EEBffiffiffifflffi 


HIS chapter does not present a complete explanation of all 
Codeview functions and operations. It does provide a 


complete and concise overview of Codeview options, command line 
semantics, and general commands. In most cases, this provides all 
you need to use Codeview to debug your application. There are three 
versions of Codeview supplied with most versions of Microsoft 
programming languages. One version works with DOS, the second 
works with Windows, and the third works with OS/2. (Some current 
Microsoft products do not provide the protected mode version of 
Codeview required for OS/2. In most cases, you can obtain OS/2 
support by using an older version of the same product.) Figure C-1 
shows a typical Codeview display. Table C-1 describes each item 
labeled on Fig. C-1. 


Codeview display breakdown. 


The Codeview display elements 


Element 


1 


Description 


Menu Bar-Contains a list of Main menu items. When you select one of 
the menu items, Codeview displays a submenu with lists of commands 
that you can perform. 


Local Window (optionalLContains a list of variables local to the current 
scope. You also can set this window to display variables local to other 
SCopes. 


Element 


3 


Description 


Code Lines-Codeview numbers each line of code within a file 
sequentially. Each external file that is called within a program uses its own 
numbering starting at one. Codeview highlights the numbers of lines 
selected as breakpoints. 
Current Location Line-Shows the line of code that Codeview will 
execute next. This line is not always visible because you can scroll 
throughout the current file. 
Window/Dialog Box Border-There are several elements to this border. 
The horizontal and vertical scroll bars allow you to scroll the display to 
show other areas of information contained in the dialog box or window. 
The double line in the lower right corner of the border allows you to size 
the dialog box or window. The right-most arrow shown in the upper left 
corner of the border allows you to maximize the dialog box or window. 
The left-most arrow in the upper left corner allows you to minimize the 
dialog box or window. The box in the upper left corner of the board 
allows you to close the dialog box or window. Finally, you can move the 
dialog box or window by grabbing the title bar in the middle of upper line. 
Command Window-Use this window to enter commands that you want 
Codeview to perform. You can scroll through this window to review the 
results of previous commands. 
Cursor-Shows the location within the Dialog or Display Windows that 
Codeview allows you to enter commands. Entry always begins at the 
location directly under the cursor. 
Scroll Bars-Allows you to scroll through the contents of the Dialog or 
Display windows using a mouse. The highlighted area shows the current 
location of the cursor within the window. The arrows determine the 
direction of scrolling. 
Mouse Pointer-Shows the current location of the mouse. Codeview 
displays the mouse pointer only if you have a mouse installed. 
Source Window-Shows the program code loaded into Codeview for 
debugging. You can display the code in one of three modes. Source mode 
shows the program code as you wrote it. Assembly-language mode 
displays the code as the compiler converted it for the processor. Mixed 
mode shows both the source code and assembly language equivalent. 


11 (Not shown) Register window (optional)-The register window shows the current status 


of the 80x86 or 8088 processor registers. You can toggle this window 
open or closed by pressing F2. A special 80386 mode allows you to view 
all the registers associated with the 80386 processor. The operand 
address at the bottom of the display shows the physical location of an 
operand (variable) in memory. 
Menu Highlight-Highlights the current menu selection. You change the 
highlight by pressing the Up or Down arrows. 
Menu-Contains selections relating to the category displayed on the Menu 
Bar. You can select a menu by pressing Alt, then the highlighted letter of 
the menu on the Menu Bar. 


Table c-1 Continued 


Element 


14 


Description 


Program Name-Displays the name of the file loaded into memory. If you 
used the Codeview switches while compiling and linking your code, the 
Program Name changes as you go between library and other source code 
modules. 


15 (Not shown) Dialog Box-Appears in the center of the display when you select a 


menu item requiring a response. The Dialog Box disappears when you 
type an answer and press Enter. 


16 (Not shown) Message Box-Appears in the center of the display when an error occurs 


or when Codeview needs to warn you about some condition. The 
Message Box disappears when you correct the error condition and press 
Enter. 


17 (Not shown) Watch window (optional)-Contains a list of selected variables and 


expressions and their current status. Codeview displays this window 
whenever you define a variable or expression to monitor. 


18 (Not shown) Memory window (optional)-Displays the contents of memory at a 


specific location. You can use more than one memory window to display 
more than one area of memory. The memory window also allows you to 
change the contents of memory. 


19 (Not shown) 8087 Window (optional)-Displays the contents of the math coprocessor 


registers or the software emulator. 


20 (Not shown) Help window (optional)-Displays the current help topic. 


Operation 


This chapter looks at only the OS/2 version of the Codeview 
product. You can use many of the same switches with the Windows 
and DOS versions of the product. To access the OS/2 version of 
Codeview, simply type CV; to access the Windows version, type 
CVW. The following examples show you the command line format for 
using Codeview: 


Ovrvw||options|executable_filename|arguments| 
CWTW| @F.iJe executable_filename |arguments| 


The Codeview option descriptions appear in the next section. The 
executable filename is any legitimate source code filename. The 
arguments are command line parameters to the executable file. 


Options 


The following options affect the way Codeview reacts to the system 
hardware and programs. All of these options are appropriate when 
using either the DOS or Windows version. (Each command line 
parameter shows which version it works with.) 


The /2 option 
CV CVW 
The /2 option permits using two monitors. The default monitor 
displays the program, while the other monitor displays Codeview 
information. 


The /8 option 
CVW 
The /8 option applies to only the Windows version of Codeview 
(CVW). This option allows you to use an 8514 display as the primary 
monitor and a VGA display as the secondary monitor. The primary 
monitor displays the application as it runs; the secondary monitor 
displays the source code. 


The /43 option 
CV CVW 
The /43 option enables the 43 line display mode of EGA equipped 
computers. 


The /50 option 
CV CVW 
The /50 option enables the 50 line display mode of VGA equipped 
computers. 


The /8 option 
CV CVW 
This option disables color presentation when using a two-color 
monitor with a CGA card. 


The /C commands option 
CV, CVW 
Use this option to execute the command in the commands field 
automatically upon Codeview start-up. 


The /F option 
CV 
Use this option to enable screen flipping. Codeview flips between 
two display pages in the graphic memory to display both Codeview 
and program screens. This option is faster than the screen swapping 
mode required for monochrome displays. Codeview disables this 
option when using two displays. 


The /G option 
CV, CVW 
Use this option to suppress snow on some CGA displays. 


The /I number option 
CV, CVW 
This option forces Codeview to handle both NMI and 8259 interrupt 
trapping when used with the /10 setting. The /11 and /I settings force 
Codeview to ignore both NMls and 8259 interrupts. Use this option 
on computers that are not 100°/o IBM compatible. 


The /LDLL and /LEXE op+.ions 
CVW 
Use this option to load an application or DLL when debugging 
Windows code. Codeview does not load debugging information for an 
external library or application when you load the application you 
want to debug. Using this switch forces Codeview to load the 
external module and search it for symbolic information. 


The /M option 
CV, CVW 
This option disables mouse support. 


The /N option 
CV, CVW 
This option forces Codeview to handle NMI interrupt trapping when 
used with the /N0 setting. The /Nl and /N settings force Codeview to 
ignore NMls. Use this option on computers that are not 1000/o IBM 
compatible. 


The /S option 
CV 
The /S option enables screen swapping. Use this option with a 
monochrome adapter, a non-IBM CGA/EGA adapter, or a program 
that uses multiple video pages. This option works slower than the 
standard screen flipping mode explained earlier. Do not use this 
option when using two displays. 


The /TSF option 
CV, CVW 
Use the Toggle State File (TSF) option to toggle the reading of 
Codeview's state and color files. The Statefileread entry in the 
Codeview section of the TOOLS.INI file determines whether the toggle 
forces Codeview to read or not read the files. The option works as an 
exclusive OR with the Statefileread entry. If you specify one or the 
other, then Codeview reads the state and color files. If you specify both 
or neither, then Codeview does not read the state and color files. 


The /X and /Y options 
CVW 
Use this option to specify the starting X and Y coordinates of the 
Codeview window within Windows. Once Codeview starts you 
cannot change the Window location or size. 


Commands and controls 


The following commands and control keys include all the keyboard 
commands used to control various aspects of the debugger display 


and program control. It also includes all commands entered at the 
prompt that affect program execution and control. 


The 8087 (7) command 
This command tells Codeview to display the contents of the 
8087/80287 chip registers in the dialog window as shown in Fig. 
C-2. It also works with 8087 emulator libraries. 
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Codeview 80x87 support window. 


Arfu-menu letter 
Pressing AIT-menu+effer brings up any of the menu entries at the 
top of the display. For example, pressing Alt-H displays the Help 
menu shown in Fig. C-3. The only menu item that doesn't always 
display a list of items is the Call menu. If you press Alt-C and nothing 
happens, then you are in the main procedure of the program; it isn't 
performing a subroutine. 


A;1+-number 
Pressing Alt-number displays the specified window on screen. For 
example, pressing Alt-8 displays the 8087 window. Table C-2 
provides a complete listing of the Windows you can display in 
Codeview. 
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The Codeview windows 


Codeview Help menu. 


Number Window Description 


0 Help 
This window contains the current help topic. (If you haven't used 
the window before, help automatically displays the Microsoft 
Advisor index.) Use the options on the Help menu to change 
topics using an index or context sensitive search. 
Displays the local variables. Change the contents of the Locals 
window using the Loco/s Opfjons entry of the Options menu. 


Displays any watch entries that you create using the options on 
the Data menu. 


Source 1 Displays the source contained in the source 1 window. You can 


modify the appearance of this display using the Source I 
W!.ndou) entry of the Options menu. 


4 Source 2 Displays the source contained in the source 2 window. You can 


modify the appearance of this display using the Source 2 
W{.ndoLu entry of the Options menu. 


Memory 1 Displays the source contained in the Memory 1 window. You can 


modify the appearance of this display using the Memory I 
Window entry of the Options menu. 


Memory 2 Displays the source contained in the Memory 2 window. You can 


modify the appearance of this display using the Memory 2 
W!.ndouJ entry of the Options menu. 


Register The Register window shows the contents of the 80x86 


processor registers. 


Table c-2 Continued 


Number Window Description 


8 8087 The 8087 window shows the contents of the 80x87 coprocessor 


registers. 


Command This window allows you to enter commands that provide 


Codeview with instructions. 


All-/ 
The Alt-/ key combination allows you to repeat the last find you 
initiated. 


All-Backspace 
Use the Alt-Backspace key combination to undo your last edit. 


Alt-F4 
Use this key combination to exit Codeview when you finish 
debugging your application. 


All-F5 
The Arrange function (Alt-F5) allows you to arrange all the windows 
on the display so that none of the windows overlap. For example, if 
you start Codeview in the default combination and display the 
Register windows, then pressing Alt-F5 will place the Register 
window on the left side of the display and reduce the sizes of the 
Local, Source 1, and Command windows appropriately. 


Assemble 
Syntax A [ac/cyress] 
The Assemble command converts 8088, 8086, 80286, 80386, and 
80486 mnemonics to executable code. The optional address field 
specifies where to place the code; otherwise, assembly begins at the 
current address. 


Breakpoint Clear 
Syntax BC [//.sf:*] 
The Breakpoint Clear command removes a single breakpoint 
(specified by list) or all breakpoints (specified by an asterisk). 


Breakpoint Disable 
Syntax BD [//.sf:*] 
The Breakpoint Disable command to disable one or all breakpoints. 
the list field specifies which breakpoints to disable. An asterisk 
disables all breakpoints. 


Breakpoint Enable 
Syntax BE [//'sf!*] 
The Breakpoint Enable command selectively enables the breakpoints 
specified by list. Using an asterisk with this command enables all 
breakpoints. 


Breakpoint List 
Syntax BL 
The Breakpoint List command displays a listing of both enabled and 
disabled breakpoints. 


Breakpoint Set 
Syntax BP [ac}cyress] [passcour7f] ["commanc/s"] 
The Breakpoint Set command places a breakpoint at the specified 
address. If the programmer does not specify an address, the breakpoint 
appears at the current program execution line. The passcour)i field 
provides a means of ignoring the breakpoint for the number of times 
specified. Codeview executes the commands entered in the 
"commar}ds" field every time it encounters the breakpoint. 


Ctrl-\ 
You can use this key combination to search for the highlighted text. 
Simply highlight the text that you want to search for, then press 
Ctrl-\ . 


Ctrl-C 
Pressing Ctrl-C halts program execution. The Ctrl-Break key 
combination performs the same function. 


Ctr]-F4 
Use this key combination to close the currently active window. 


Ctrl-F5 
Codeview allows you to maximize windows to see more of the 
contents of a window or minimize them so they don't take any screen 
real-estate. The Ctrl-F5 key combination allows you to restore the 
window to its previous condition. 


Ctrl-F7 
You can move the active window by pressing the Ctrl-F7 key 
combination and moving it with the arrow keys. 


Ctrl-F8 
You can change the size of the active window by pressing the Ctrl-F8 
key combination, then pressing the arrow keys. 


Ctrl-F9 
Instead of closing the active window when you get done with it, you 
can minimize it to an icon using the Ctrl-F9 (minimize) key 
combination. This allows you to access the window quickly without 
resorting to using the Window menu. Figure C-4 shows a typical 
display setup for quick window access using a mouse. 
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Arranging the Codeview display for maximum use. 


Ctrl-Flo 
The maximize key combination fills the entire display area with the 
contents of the active window. You can use it when you need to see 
more information. 


Ctrl-Ins 
You can copy any highlighted text to a clipboard using the Ctrl-Ins 
key combination. Simply highlight the text you want to copy and 
press Ctrl-Ins. 


Ctrl-U 
The Ctrl-U key combination performs the same function as pressing 
Alt-D, then D. Codeview displays a listing of the current 
watchpoints, as shown in Fig. C-5. Selecting one of the watchpoints 
and pressing Enter deletes it. 


!=E=8 =:::=::: #=: #:i:==: = 15i .11, 


Codeview Delete Watch dialog box. 


Ctrl-W 
Use the Ctrl-W key combination to invoke the Add Watch option of 
the Watch menu (Fig. C-6). It performs the same function as pressing 


Figure C-6 
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Codevieu) Add Watch dialog box. 


Alt-D, then A. This option causes Codeview to display the contents 
of the selected variable or expression during program execution. 


Display Mode Selection 
Syntax S[d/'sp/ay[mode]] [/opf/'or}] 
This command allows you to display and modify the current state of 
the display. Using S by itself displays the status of the current Source 
Code window. The c}/'sp/ay argument contains the number of the 
Source Code window that you want to modify. Using Scy/.sp/ay selects 
the window number specified by c}/.sp/ay. For example, Sl would 
select the first source code window. If you do not specify a window, 
then Codeview assumes you want to modify the current window. The 
mocye argument defines what type of display to create: + for source 
code only, - for assembly language only, and & for mixed source and 
assembly code. For example, Sl + would set the first source code 
window to a source code only display. The opt/.on argument allows 
you to modify the appearance of the display. There are six options: 
show addresses (A), show machine code (8), upper case instructions 
(C), mixed mode order-source line (L), show symbolic name (S), and 
trace on (T). To turn an option on, simply follow it with a plus sign. 
For example, to show addresses in source code window one, you 
would type Sl /A+ in the Command window. To turn an option off, 
simply type a minus sign. 


Display Expression 
Svula[x ? expression |,format] 
Use the Display Expression command to display any valid Codeview 
expression. The express/.on field contains the expression to evaluate. 
The optional format field specifies the display format. 


Down arrow 
The down arrow moves the cursor down one line in the display or 
dialog box. 


Dump 
Syntax D [fype] [ac/c/ress i range] 
The Dump command displays data contained in the area specified by 
address in both hexadecimal and ASCII formats. Using D by itself 
produces a display of the data pointed to by DS:0000 or the data 
after the previous display. The range field specifies a starting and 
ending address to display. Using a segment override allows display of 
data not pointed to by the DS register. Adding a dump type specifier 
changes the default dump display. The following examples show all 
the different forms of dump: 


D CS:0 50 ;Dumpsthedatapointedto bythecs 


;register from offset 0 to 50. 


DA CS:0 50 ;DumpsthesamedatainAScllformat. 
DB CS:0 50 


DD CS:0 50 


DI CS:0 50 


DIU CS:0 50 


DIX CS:0 50 


DL CS:0 50 


DLU CS:0 50 


DLX CS:0 50 


;Dumps the same data in byte format. 
;Dumps the same data in double word format. 
;Dumps the same data in integer format. 
;Dumps the same data in unsigned integer format. 
;Dumps the same data in hexadecimal integer format. 
;Dumps the same data in long real format. 
;Dumps the same data in unsigned long real format. 
;Dumps the same data in hexadecimal long real 


;format. 


:0 50 ;Dumpsthesame data in real format. 
:0 50 ;Dumpsthesamedatain long realformat. 
:0 50 ;Dumpsthesamedatain lo-byte real format. 
0 50 ;Dumpsthesamedata inword format. 


End 
Moves the cursor to the end of the command buffer in the dialog 
window or source file/program instructions in the display window. 


Enter 
Syntax E [lype] ac/c/ress [//.sf] 
Use the Enter command to change the contents of memory. There is 
one non-optional field associated with this command. Codeview will 
treat the E as execute unless the acyc/ress field contains a valid address. 
As with other commands, this command assumes the segment address 
of the DS register unless the address field contains a segment override. 
The //'sf field contains the data Codeview enters at that address. If the 
//.sf field is empty, Codeview presents an area for entering the data. The 
type field determines the size of data entered into memory. The 
following examples show how to use this command: 


E 0001 


EA 0001 


EB 0001 


ED 0001 


El 0001 


EIU 0001 


EIX 0001 


EL 0001 


ELU 0001 


ELX 0001 


EW 0001 


22 ;Enter data in the default type. 
"HI" ;Enter ASCII. 


44 ;Enter a byte. 
44 ;Enter a double word. 
-12 ;Enter an integer. 


12 ;Enter an unsigned integer. 
12 ;Enter a hexadecimal integer. 


12 ;Enter a long real. 


12 ;Enter an unsigned long real. 
12 ;Enter a hexadecimal long real. 
ADOC ;Enteraword. 


Examine Symbols 
Svri+a[x Xscope |context] |regular_expression| 
The Examine Symbols command displays symbolic information about 
a program, as shown in Fig. C-7. There are six different scopes that 
you can specify with this command: lexical, function, module, 
executable, public, and global. To specify a scope, simply type its first 
letter. Use the asterisk to tell Codeview that you want to look at all 
scopes. The confexf specifies where you want Codeview to look. It 
follows the format: 


{[funcf/'or7], [modL//e], [DLL/EXE]} [ob/'ecf] 
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Using the Codeview Command windou). 


The regu/ar_express/.on entry allows you to look for specific entries. 
There are several wildcard operators associated with this argument. 
The period matches any single character. The carot matches any text 
at the beginning of the line. The dollar sign matches text at the end 
of the line. The asterisk matches zero or more repetitions of the 
characters preceding it. Finally, text appearing within square brackets 
has special significance. Using a carot in front of a set of characters 
matches everything but those characters. Using a dash matches all 
ASCII characters within the range specified by the characters before 
and after the dash. For example, [A -C] would match all symbols 
beginning with letters from A to C. 


Execute 
Syntax E 
The Execute command, which is renamed Animate in newer versions of 
Codeview, performs the same function as the Go command in slow 
motion. This allows the observer to see the changing of the contents of 
the CPU registers, and any watched variables or expressions. 


FI 
Displays the online Help menu. 


Figure C-7 


F2 
Switches the display between showing/not showing the CPU register 
contents. 


F3 
Use this key to change the output display between source code, 
mixed source code and assembly, and assembly onl`y. 


F4 
This key toggles the display between the debugger and program 
Outputs. 


F5 
Performs the same function as the Go command. The program 
executes until Codeview encounters a breakpoint or the file ends. 


F6 
Toggles the cursor between the displayed windows. 


F7 
This option is active when the cursor is in the display window. If the 
line pointed to by the cursor represents code and Codeview does not 
encounter another breakpoint or the end of the executable file, then 
the program executes to the cursor line. 


F8 
Use this key to execute a Trace command. 


F9 
This key tells Codeview to add a breakpoint to the line pointed to by 
the cursor. 


Flo 
Pressing this key executes a program step command. Codeview steps 
over any calls or interrupts to the next displayed instruction. 


Go 
Sghialx G break_address 
The Go command continuously executes program instructions until 
it encounters the address specified by break_ac/c/ress, a preset 
breakpoint, a Ctrl-C or Ctrl-Break, or the end of the executable 


f ile . 


Graphic Display 
Syntax ?? var/.ab/e[,C] 
The Graphic Display command provides an enhanced view of 
structured variables. The var/.ab/e field states which variable to 
observe. The optional C entry allows an ASCII display of single byte 
entries. The graphic display is similar in nature to the Watch 
command. 


Help 
Syntax H 
Use this command to obtain help on various topics. It performs the 
same function as the Fl key. 


Home 
Pressing the Home key moves the cursor to the beginning of the 
command buffer in the dialog window or source file/program 
instructions in the display window. 


Input and Output Ftedirection 
Sgutalx --device_name 
The Input and Output command changes both the default input 
and output to the device specified by device name. The following 
example shows commands specifically used during input/output 
redirection : 


T>F3EDIR.TXT 
* This is a Comment. 


<lNFILE.TXT 


11 


;Bedirect the output. 
;Add a comment to the file. 
;Bedirect the input. 
;Short command processing delay. 
;Longer command processing delay. 
;Pause until the programmer 
;presses a key. 


Input Redirection 
Svulalx devi.ce_name 
The Input Redire;tion command changes default input from the 
console to the specified device name. 


Memory Compare 
Svuldx MC range address 
Use the Memory Compare command to compare two memory 
ranges. It replaces the Compare command found in previous 
versions of Codeview. The range argument contains the range of 
memory you want to compare. The range consists of a starting and 
ending address. The ac/dress argument contains the address of the 
second area of memory that you want to compare with the selected 
range. 


Memory Dump 
Syntax*MD 
See the Dump command for a description of the Memory Dump 
command. 


Memory Enter 
Syntax*ME 
See the Enter command for a description of the Memory Enter 
command. 


Memory Fill 
SvTitalx MF range value_list 
The Memory Fill command replaces the Fill command used in 
previous versions of Codeview. The range argument contains a 
starting and ending address value. It specifies the range of memory 
that you want to fill. The va/ue_//'sf argument contains a list of values 
you want to place in the selected range. You can use the Memory 
window to monitor the results of using the Memory Fill command. 
Figure C-8 shows how you can use the Memory window to monitor 
the results of using Memory Fill command. 
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Using the Codeview Memory window. 


Memory Move 
Syntax MM range ac}c/ress 
The Memory Move command replaces the Move command used in 
previous versions of Codeview. The rar7ge argument contains the 
starting and ending address of the range of memory you want to 
move. The ac/c}ress argument contains the starting address where 
you want to move the data. 


Memory Search 
Svatz[x MS range li.st 
Use the Memory Search command to look for specific items in a 
range of memory. It replaces the Search command used in previous 
versions of Codeview. The rar7ge argument contains the starting and 
ending address range of memory you want to search. The //.sf 
argument contains the data you want to search for. 


Option 
Syntax 0 [opf/.on] [+:-] 
The Option command changes the default condition of items 
appearing on the options menu. Valid options for the opt/.on field 


Figure C-8 


include: A for status bar, F for flip/swap screens, 8 for bytes coded, 
C for case-sensitive, H for horizontal scroll bar, L for show symbol 
address, N for Native, S for symbols, V for vertical scroll bars, and 3 
for 386 mode. Adding a plus sign to the end of the option turns it 
on, and a minus sign turns it off; otherwise, Codeview displays the 
current state of the option. Entering 0 with no arguments displays 
the current state of all options. For example, typing OL would show 
the state of the Show Symbol Address option. 


The Show Symbol Address option contains several suboptions 
including: L for lexical, F for function, M for module, E for EXE, and 
G for global. Unlike the other options, you set or reset these 
suboptions simply by including or excluding their letter on the 
command line. For example, typing OLFMEG sets all the options to 
on. On the other hand, typing OLG set only the lexical and global 
scoping to on. 


Output Redirection 
Syntax [T] >[>] cyev/'ce_r7ame 
The output redirection command changes the default output to the 
device specified by cyev/.ce_r7ame. The optional T prefix allows 
simultaneous output to both display and device. Using the second 
greater-than symbol allows Codeview to append the new output to 
the end of an old file. 


PgDn 
PgDn moves the cursor one page down the command buffer in the 
dialog window or source file/program instructions in the display 
window. 


Pgup 
Pgup moves the cursor one page up the command buffer in the 
dialog window or source file/program instructions in the display 
window. 


Port Import 
Syntax I port 
This command tells Codeview to import data from the specified port. 
It displays the data in the current default radix. 


Port Output 
Syata[x a port byte 
Use the Port Output command to output the value specified in the 
byre field to the specified port. 


Program Step 
Syntax P Cour7f 
The Program Step command executes a program step. If it 
encounters a procedure, routine, or interrupt, it executes all the code 
to the next executable step in the displayed procedure. The program 
step command normally executes once; specifying a value in count 
executes it that number of times. 


Quit 
Syntax a 
The Quit command closes all program files and returns the 
programmer to the DOS prompt. 


Radix 
Syntax N [racy/'x_r}umber] 
Use the Radix command to change the default base used to display 
numeric data. Entering N with no argument displays the current 
radix. Valid radix arguments are 8 for octal, 10 for decimal, and 16 
for hexadecimal. 


Register 
Syntax B [reg/.sf er_r7ame] [=[express/.or7]] 
Use this command without any parameters to display the contents of 
all registers. When using an 80386-equipped machine, Codeview 
displays all 32-bit registers. 


Codeview displays the current value of the register and asks f or a 
new value when the reg/.sf er_r7ame field contains a valid register 
name but the express/.on field is blank. It automatically replaces the 
designated register with an expression when one is supplied. 


Redraw 
Syntax @ 
The Redraw command redraws the Codeview display. 


Ftestart 
Svula[x L arguments 
The Restart command returns the CPU registers and program 
variables to the conditions encountered on program entry. Codeview 
passes any parameters placed in the argumer)fs field to the program 
as command line variables. 


Screen Exchange 
Syntax \ [f/'me] 
This command performs the same function as pressing the F4 key. 
Use it to see executing program output. The I/'me field operates only 
with the protected mode version. The protected mode version screen 
returns to the debugging display automatically. The optional I/.me field 
sets the amount of time that elapses before the screen returns to the 
debugging display. 


Search Source File 
sgTitax I |regular_expression| 
The Search Source File command is similar in nature to the Search 
Memory command. Instead of searching memory, Codeview searches 
a source file for the specified regular expression. Codeview then 
places the cursor where it found the expression. 


Shell Escape 
Syntax ! [commar}cys] 
Use the Shell Escape command to suspend debugging temporarily to 
execute a DOS command. When no command appears in the 
commands field, Codeview executes a copy of the command 
processor; otherwise, it executes the command. 
Shift-FI 
Pressing Shift-Fl displays the help table of contents. This allows you 
to search for any topic contained in the help files. 


Shift-F5 
Tiling the windows displayed on screen allows you to display your 
windows in a little more logical sequence than the arrange option. 
Unfortunately, this arrangement doesn't always provide the best view 
of the information the window contains. Figure C-9 shows a typical 
tiled setup. Simply press Shift-F5 to obtain this feature. 
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Using the Codeview Register window. 


The Codeview Quick Watch dialog box. 


Shift-F9 
Pressing Shift-F9 is the fastest way to create a new watch data 
structure to the Watch window. Simply highlight a variable or other 
entity and press Shift-F9. Codeview displays a dialog box that asks 
how you want the variable added to the Watch window, as shown in 
Fig. C-10. 


Figure C-9 


Shift-]ns 
Use the Shift-Ins key combination to paste the contents of the 
clipboard to the current cursor position. There are limitations on 
pasting text. For example, you cannot copy the contents of the 
clipboard to the Source 1 or Source 2 windows. 


Stack Trace 
Syntax K 
The Stack Trace command displays a list of calls made by a program 
during program execution. 


Tab Set 
SvulzLx # number 
Use the Tab Set command to change the spacing between tabs. 


Trace 
Syntax T [coun£] 
The Trace command causes Codeview to execute one line of code. If 
the code calls another procedure/routine or interrupt, Codeview 
shows that code as the next executable instruction. The Trace 
command executes once or the number of times specified by the 
optional count field. 


Trace Speed 
Syntax TsiM!F 
The Trace Speed command determines how fast the trace animation 
runs. The S option pauses 1/2 second between steps, the M option 1/4 
second. There is no delay when you use the F option. 


Unassemble 
Syntax U [acyc}ress: range] 
Use the Unassemble command to produce an unassembled listing of 
an executable file. Unless the command includes an address, 
Codeview displays one screen of unassembled data starting at the 
address pointed to by CS:IP. When the command includes a range of 
addresses, Codeview unassembles code from the starting to ending 
address. 


Up arrow 
Moves the cursor up one line in the display or dialog box. 


Use Language 
Sghialx USE language_name 
The Use Language command allows you to change the language 
evaluator that Codeview uses during debugging. The default setting is 
AUTO, which tells Codeview to automatically select the correct 
evaluator. 


View Memory 
Syntax VM [w/.nc}ow] [fype] [adc/ress] [opf/.or7s] 
The View Memory command allows you to view memory in various 
formats using either of two Memory windows. The w/'r}c}ow argument 
allows you to specify a particular window. The type argument 
determines how Codeview formats the window. You can choose any 
of the following formats: A for ASCII characters, 8 for byte, I for 
integer, lu for unsigned integer, lx for hexadecimal integer, L for 
long real, LU for unsigned long real, LX for hexadecimal long real, B 
for real, PL for long real, and BT for 10-byte real. The ac/c/ress 
argument specifies the starting address of the display. There are 
several options associated with this command. The /B[+ : -option 
enables or disables the display of raw data. The /L[+ : -] option 
enables or disables automatic (live) display updates. The /F[* i /er7gfh] 
determines the length of the displayed items. If you use the asterisk, 
then Codeview displays as many items as will fit in the Memory 
window. Using the /er7grh argument allows you to specify a fixed 
number of characters from 1 to 125. 


View Source 
Syntax VS [cJ/.sp/ay [mocJe]] [/opt/.or)] 
The View Source command provides the same functionality as the 
Display Mode Selection Command described earlier. 


Add Watch 
Sgatalx W? expression|, format| 
Use the Add Watch command to add an expression to the watch list. 
The express/'or7 argument contains the name of a variable or other 
expression. The formaf argument contains the format that you want 


to use to display the expression. For example, you could type W? 
Message,S at the Command window to add a variable called 
Message using the string format. 


Delete Watch 
Syulalx WC number'i* 


The Delete Watch command allows you to remove either one or all of 
the watch expressions from the Watch window. Specifying a 
particular number removes one expression. Using the asterisk 
removes all the expressions from the Watch window. 


Watch List 
Syntax WL 


The Watch List command displays a list of the current watch 
expressions along with their watch number. 


Table C-3 


Expressions, symbols, consfants, 
strings, and display formats 


The following sections describe the expressions, symbols, constants, 
strings, and display formats used in Codeview. 


Expressions 


The expressions used in MASM coincide with the same expressions 
used in C. However, MASM does not use some of the symbols used in 
C. Table C-3 presents only the symbols used in MASM and their 
order of precedence. 


The Codeview Assembly language expressions 


Precedence Operators 


1 ()[]-=. 


2 ! ~-1 (type) ++ --*2 &3 sizeof 


Precedence Operators 


3 ¥2. /O/o= 
4+-1 
5 <><->- 
6 --1- 
7&& 
80 
9 --+ ----- *--/ --O,rJ,-- 


10 BY (byte) WO (word) DW (double word) 


1 The precedence 2 minus sign is the unary (number value) operator. The precedence 4 minus 


sign is the binary (subtraction) operator. 


2 The precedence 2 asterisk represents the pointer operator. The precedence 3 asterisk is the 


multiplication operator. 


3 The ampersand at precedence 2 is the address-of operator. Codeview does not support the 


ampersand as a bitwise AND operator. 


Symbols 


Symbols represent variables, registers, segment addresses, offset 
addresses, or full 32-bit addresses. Codeview accepts requests for 
information about any valid register, address, global variable, or 
variable in the current procedure. 


Constants 


A constant is any integer number that Codeview uses as part of a 
command. The default radix that Codeview uses with assembly language 
programs is hexadecimal. To change the radix, use either the radix 
command described earlier to .change the radix or use a radix override in 
front of the number permanently.`T`he form of a number with a radix 
override is: `` 


override + number 


as shown here: 


16 ;This represents l6 in the default radix. 
016 ;This represents l6octal. 


Onl6 ;This represents 16 decimal 
Oxl6 ;This represents 16 hexadecimal 


Strings 


A string consists of characters delimited by double quotes. Codeview 
uses strings as part of some commands (for instance searches). The 
following example shows the difference between a string and 
nonstring: 


"This is a string." 


This is not a string. 


Table C-4 


Display formats 


Codeview provides a set of nine display format extensions to various 
commands. Table C-4 provides a list of these extensions and their 
meanings. 


The Codeview display format specifiers 


Char. Output format 


d Signed Decimal Integer 


1 Signed Decimal Integer 


u Unsigned Decimal Integer 


o Unsigned octal Integer 


f Signed Floating point Decimal value (6 Places) 


e or E Signed Floating point Decimal value using scientific Notation (6 Places) 


g or G Either F or E Format (whicheve4r,is in'ore compact) 
c Single character 


s Characters printed to the First Null character 


Note: Using the capitalized version of a format specifier results in uppercase letters in the output. 


Restrictions 


The use of the Codeview debugger requires you to observe the 
following six restrictions on program type: 


> Codeview can debug programs with include files. You cannot 


see the contents of the include file. 


> You cannot use the standard EXEPAC utility or any LINK pack 


options on files used with Codeview. You can use the CVPACK 
utility to reduce executable file size. 


> The programs cannot alter the environment. Codeview 


discards any changes to the environment when it exits. 


> Some programs might experience problems if they directly 


access the Program Segment Prefix (PSP). Codeview 
preprocesses the PSP the same way C programs do. 


In addition to the previous restrictions, the protected mode version of 
Codeview has the following two restrictions: 


> Only one copy of Codeview can run at a time. 


> If you don't use the /2 option when debugging and the program 


calls dynamic link library functions outside the API, then 
Codeview cannot access the program's environment, drive, or 
directory. 


Index 


0/o operator, 44 
& operator, 10 
* operator, 44 


+ operator, 44 
/ operator, 44 
// operator, 44 
< less than operator, 10 
> greater than operator, 10 
- operator, 44 
= equal operator, 10 
\ operator, 10 
i operator, 10 
0 operator, 44 
OxOOOO function, 
OxOool function, 
Ox0002 function, 
Ox0003 function, 


468 


Ox0004 function, 463 
0x0020 function, 464 
0x0021 function, 464 
0x0040 function, 374 
0x0041 function, 375, 399 
0x0042 function, 395-396, 399 
0x0043 function, 399-400, 464-465 
0x0044 function, 396, 400, 465, 469 


Ox0045 function, 400, 465 
0x0046 function, 396, 400-401 
0x0047 function, 401 
0x0048 function, 396-397, 401 
0x004B function, 401 
0x004D function, 397 
0x004E function, 397 
0x0050 function, 362-364 
0x0051 function, 364, 370-371 
0x0052 function, 364 
0x0053 function, 371, 364-365, 401- 


402 


0x0054 function, 365, 371, 402 
0x0056 function, 365, 371 
0x0057 function, 365, 371 
0x0058 function, 365-366, 371-372 
0x0059 function, 366, 372 
0x005A function, 366, 372 
0x005C function, 366, 372 
0x005D function, 367, 372 
0x005E function, 367 
0x0060 function, 372, 375, 466 
0x0061 function, 372, 402 
0x0062 function, 372-373, 397, 402- 


403 


Ox0063 function, 373, 403, 466, 469 
0x0064 function, 373, 397, 403, 467, 


469 


0x0065 function, 373, 403, 467, 469- 


470 


0x0066 function, 373, 398, 403 
0x0067 function, 373, 404 
0x0068 function, 373-374, 404 
0x0069 function, 398, 404 
0x006A function, 374, 398 
0x006B function, 374 
0x006D function, 404 
0x006E function, 399 
0x0070 function, 360 
0x0071 function, 361, 367 
0x0072 function, 361, 404-405 
0x0073 function, 361, 367, 405 
0x0074 function, 361, 367-368, 405- 


406 


0x0075 function, 361, 368-369 
0x0076 function, 361-362, 369 
0x0077 function, 369 
0x0078 function, 369 
0x0079 function, 369 
0x007A function, 370 
0x007B function, 370 


A 
AAA command, 64 
AAD command, 64 
AAS command, 64 
ABBREV function, 22 
ABLOCKCGA command, 141 
ABLOCKMFl command, 141 
ABS function, 22 
ABS instruction, 168 
Acquire command, 474 
ACURSOR command, 141 
ADC command, 64 
ADD command, 64 
ADD instruction, 168 
ADDC instruction, 168 
ADDI instruction, 168 
ADDK instruction, 168 
ADDRESS command, 15 


ADDRESS function, 22 
ADDXY instruction, 168 
AERASE command, 141 
AND command, 65 
AND instruction, 168 
AND operator, 10 
ANDI instruction, 168 
ANDN instruction, 168 
application programming interface (API) 


disk, 409-470 
keyboard and mouse, 355-392 
multimedia, 471-505 
parallel/serial ports, 393-408 
video, 102-354 


applications, testing, 52-54 
ARG command, 15ARG function, 22- 


23 


ARPL command, 84 
ASCII 


chart organized by type, 537-539 
table of codes, 529-536 


ASCROLL command, 141 
ASCUR command, 141 
ASFONT command, 141 
assignments, REXX, 8 
AXIAIE command, 141 


8 
82X function, 23 
BEEP function, 23 
BITAND function, 23 
BITBLT instruction, 177 
BITOR function, 24 
BITXOR function, 24 
Boolean operators, 9-10 
BOUND command, 86 
BSF command, 88-89 
BSR command, 89 
BSWAP command, 97 
BT command, 89 
BTC command, 89 
BTR command, 89 
BTS command, 89 
BTST instruction, 168 
Builder/2 , 489-494 


C 
C2D function, 24 
C2X function, 24 
CALL command, 4, 15-16, 66-67 
CALL instruction, 168 
CALIA instruction, 168 
CALLR instruction, 169 
Capability command, 474-475 
CBW command, 64 
CDQ command, 88 
CD_IS_ALIVE instruction, 177 
CENTER function, 24-25 
CHARIN function, 25 
CHAROUT function, 25 
CHARS function, 25 
CLC command, 71 
CLD command, 71 
CLEAR_FRAME_BUFFER instruction , 


177 


CLEAR_PAGE instruction, 178 
CLEAR_SCREEN instruction, 178 
CLI command, 71 
Close command, 475 
CLR instruction, 169 
CLRC instruction, 169CLTS command, 


86 


CMC command, 71 
CMD command, 4 
CMD files, 3-5 
CMP command, 64 
CMP instruction, 169 
CMPI instruction, 169 
CMPSB command, 71 
CMPSD command, 93 
CMPSW command, 71-72 
CMPXCHG command, 96 
CMPXCHG8B command, 98 
CMPXY instruction, 169 
Codeview, 613-644 


commands and controls, 619-641 
constants, 642-643 
display elements, 614-616 
display formats, 643 
expressions, 641-642 
operation, 616 


options, 617-619 
restrictions, 644 
strings, 643 
symbols, 642 


Command command, 4 
commands (see a/so functions) 


8514/A AI, 141-142 
Codeview, 619-641 
processor, 63-101 
REXX, 15-22 


comments, REXX, 7 
COMPARE function, 25-26 
compilers and compiling 


Borland C, xii-xiii 
installation, 50-52 


CONDITION function, 26 
Connector command, 475-476 
constants, Codeview, 642-643 
COP2GSP instruction, 178 
COPIES function, 26 
coprocessors, math, 81-83, 95-96 
CPUID command, 99 
CPW instruction, 169, 178 
CREATE_ALM instruction, 178 
CREATE_ESYM instruction, 178 
CVXYL instruction, 169 
CWD command, 64 
CWDE command, 88 


D 
D2C function, 28 
D2X function, 28 
DAA command, 64 
DAS command, 64DATATYPE function, 


26 


DATE function, 26-27 
DEC command, 64 
DEC instruction, 169 
DELETE_FONT instruction, 178 
DELSTRING function, 27 
DELWORD function, 27 
Developer Connection, 2, 54-55 
device drivers, 358-360, 462, 470 
DIGITS function, 27 
DINT instruction, 169 


DIRECTORY function, 28 
disk API, 409-470 
display adapters, 8514/A, 139 
display formats, Codeview, 643 
display modes, 137-140 
DIV command, 64 
DIVS instruction, 169 
DIVU instruction, 169 
DO FOREVER..END,13 
DO UNTIL..END,12 
DO WHILE..END,12 
DO..END,11-12 
DOS error codes, 541-571 
DOS functions, 411-470, 508-524 
DOSAllocMem function, 508-509 
DOSAllocsharedMem function, 509- 


511 


DOscancelLockRequest function, 412- 


413 


DOsclose function, 413-414 
DOSCopy function, 414-416 
DOscreateDir function, 416-417 
DOSDelete function, 417-418 
DOSDeleteDir, 418-419 
DOSDevloctl functions, 357-375, 394- 


408, 460-462 
categories, 358-359 
return codes, 357 


DOSDupHandle function, 419-420 
DOSEditName function, 420-421 
DOSEnumAttrib function, 421-423 
DOSFindclose function, 423-424 
DOSFindFirst function, 424-426 
DOSFindNext function, 426-427 
DOSForceDelete function, 427-428 
DOSFreeMem function, 511 
DOSFSAttach function, 428-429 
DOSFSctl function, 429-430 
DOSGetNamedsharedMem, 512-513 
DOSGetsharedMem function, 513-514 
DOSGivesharedMem function, 514-516 
DOSMove function, 431-432 
DOSopen function, 432-434 
DOsphysicalDisk function, 411-412 
DOSQuerycurrentDir function, 434-435 


DOSQuerycurrentDisk function, 435-436 
DOSQueryFHstate function, 436-437 
DOSQueryFilelnfo function, 437-438 
DOSQueryFSAttach function, 438-440 
DOSQueryFslnfo function, 440-441 
DOSQueryHType function, 441 
DOSQueryMem, 516-517 
DOSQuerypathlnfo function, 442-443 
DOSQuerysyslnfo function, 443-444 
DOSQueryverify function, 444 
DOSRead function, 444-445 
DOSResetBuffer function, 445-446 
DOSscanEnv function, 446-447 
DOssearchpath function, 447-448 
DOssetcurrentDir function, 448-449 
DOssetDefaultDisk function, 449 
DOssetFHstate function, 450-451 
DOssetFilelnfo function, 451-452 
DOssetFileLocks function, 452-453 
DOssetFileptr function, 453-454 
DOssetFilesize function, 454 
DOssetFslnfo function, 455 
DOssetMaxFH function, 456 
DOssetMem, 518-520 
DOssetpathlnfo function, 456-457 
DOssetRelMaxFH function, 457-458 
DOssetverify function, 458 
DOsshutDown function, 459 
DOSsubAllocMem, 520 
DOSsubFreeMem, 521 
DOSsubsetMem, 521-523 
DOSsubunsetMem, 523-524 
DOswrite function, 459-460 
DRAV instruction, 169 
drawing, 103 
DRAW_LINE instruction, 178 
DRAW_OVAL instruction, 178 
DRAW_OVAIARC instruction, 179 
DRAW_PIEARC instruction, 179 
DRAW_POINT instruction, 179 
DRAW_POLYLINE instruction, 179 
DRAW_RECT instruction, 179 
DROP command, 17 
DSJ instruction, 170 
DSJEQ instruction, 170 


DSJNE instruction, 170 
DSJS instruction, 170 
DSK functions, 462-467 


E 
Echo command, 4 
editors and editing, 59-61 


EPM, 59-60 
HyperwriteA, 60-61 
SlickEdit, 59 
Tiny, 59 


EINT instruction, 170 
EMU instruction, 170 
EndLocal command, 4 
ENTER command, 86 
environment, optimizing programming, 


49-52 


EPM, 59-60 
error codes, 540-612 


DOS, 541-571 
KBD, 541-571 
MOU, 541-571 
Presentation Manager, 572-612 
VIO, 541-571 


ERRORTEXT function, 28 
ESC command, 71 
EXGF instruction, 170 
EXGPC instruction, 170 
Exit command, 4, 17 
Exitproc command, 4 
expressions 


Codeview, 641-642 
REX, 43-44 


Extended Graphics Array (XGA), 197- 


206 


F 
F2XMl command, 80 
FABS command, 73 
FADD command, 73 
EADDP command, 73 
FBLD command, 77 
FBSTP command, 77 
FCHS command, 73 


FCLEX command, 78 
FCOM command, 75 
FCOMP command, 76 
FCOMPP command, 76 
FCOS command, 94 
FDECSTP command, 78 
FDISI command, 78 
FDIV command, 73 
FDIVP command, 73-74 
FDIVR command, 74 
FDIVRP command, 74 
FENI command, 78 
FFREE command, 78 
FIADD command, 74 
FICOM command, 76 
FICOMP command, 76 
FIDIV command, 74 
FIDIVR command, 74 
FIELD_EXTRACT instruction, 179 
FIELD_INSERT instruction, 179 
FILD command, 77 
file formats, 490, 496-497 
file system driver (FSD), 413 
FILESPEC function, 28 
FILL L instruction, 170 
FILL XY instruction,171 
FILL_CONVEX instruction, 179-180 
FILL_OVAL instruction, 180 
FILL_PIEARC instruction, 180 
FILL_POLYGON instruction, 180 
FILL_RECT instruction, 180 
FIMUL command, 74 
FINCSTP command, 78 
FINIT command, 78 
FIST command, 77 
FISTP command, 77 
FISUB command, 74 
FISUBR command, 74 
flags, 81, 86-87, 94-95,100-101 
FLD command, 77 
FLDl command, 76 
FLDCW command, 78 
FLDENV command, 78 
FLDL2E command, 76 
FLDL2T command, 76 


FLDLG2 command, 76 
FLDLN2 command, 76-77 
FLDPI command, 77 
FLDZ command, 77 
FLUSH_ESYM instruction, 180 
FLUSH_EXTENDED instruction, 180 
FMUL command, 74 
FMULP command, 74-75 
FNCLEX command, 78 
FNDISI command, 78-79 
FNENI command, 79 
FNINIT command, 79 
FNOP command, 79 
FNSAVE command, 79 
FNSTCW command, 79 
FNSTENV command, 79 
FNSTSW command, 79 
For command, 5 
FORM function, 28 
FORMAT function, 28 
formatting, REXX, 44-45 
FPATAN command, 80 
FPREM command, 75 
FPREMl command, 93 
FPTAN command, 80 
FRAME_OVAL instruction, 180-181 
FRAME_RECT instruction, 181 
FRNDINT command, 75 
FRSTOR command, 79 
FSAVE command, 79 
FSCALE command, 80 
FSETPM command, 86 
FSIN command, 94 
FSINCOS command, 94 
FSQRT command, 75 
FST command, 77 
FSTCW command, 79 
FSTENV command, 80 
FSTP command, 77 
FSTSW command, 80 
FSUB command, 75 
FSUBP command, 75 
FSUBR command, 75 
FSUBRP command, 75 
FTST command, 76 


FUCOM command, 93 
FUCOMP command, 93-94 
FUCOMPP command, 94 
functions (see a/so commands) 


DOS, 411-470, 508-524 
DOSDevloctl, 357-375, 394-408, 
460-462 
DSK, 462-467 
GPI, 206-288 
KBD, 376-384 
MOU, 384-392 
naming conventions, xvii-xviii 
PDSK, 467-470 
PMREXX, 42-43 
REXX, 22-42 
REXX MCI, 482-483 
VIO, 103-136 
WIN, 288-354 


FUNCTION IMPLEMENTED 


instruction, 181 


FUZZ function, 29 
FWAIT command, 80 
FRAM command, 76 
FXCH command, 77 
EXTRACT command, 75 
FYL2X command, 80 
FYL2Xpl command, 80 


G 
GETPC instruction, 171 
GETST instruction, 171 
GET_COLORS instruction, 181 
GET_CONFIG instruction, 181 
GET_CURS_STATE instruction, 181 
GET_CURS_XY instruction, 181 
GET_ENV instruction, 181 
GET_FONTINFO instruction, 181 
GET_ISR_PRIORITIES instruction, 182 
GET_MODEINFO instruction, 182 
GET_NEAREST_COLOR instruction , 


182 


GET OFFSCREEN MEMORY 


instruction, 182 


GET_PALET instruction, 182 


GET PALET_ENTRY instruction, 182 
GET_PIXEL instruction, 182 
GET_PMASK instruction, 182 
GET PPOP instruction, 183 
GET_TEXTAITR instruction, 183 
GET_TRANSP instruction, 183 
GET_VECTOR instruction, 183 
GET_VIDEOMODE instruction, 183 
GET_WINDOWING instruction, 183 
GET_WKSP instruction, 184 
Goto command, 5 
GPI functions, 206-288 
GpiAnimatepalette function, 207 
GpiAssociate function, 207 
GpiBeginArea function, 208 
GpiBeginElement function, 208 
GpiBeginpath function, 208 
GpiBitBlt function, 208-209 
GpiBox function, 209-210 
GpicallsegmentMatrix function, 210 
Gpicharstring function, 210-211 
GpicharstringAt function, 211 
Gpicharstringpos function, 211-212 
GpicharstringposAt function, 212 
GpicloseFigure function, 212 
Gpiclosesegment function, 213 
GpicombineRegion function, 213 
Gpicomment function, 213 
Gpiconvert function, 213-214 
GpiconvertwithMatrix function, 214 
GpicopyMetaFile function, 214 
Gpicorrelatechain function, 215 
GpicorrelateFrom function, 215 
Gpicorrelatesegment function, 215-216 
GpicreateBitmap function, 216 
GpicreateLogcolorTable function, 216- 


217 


GpicreateLogFont function, 217 
Gpicreatepalette function, 217 
Gpicreateps function, 217-218 
GpicreateRegion function, 218 
GpiDeleteBitmap function, 218 
GpiDeleteElement function, 218 
GpiDeleteElementBetweenLabels 


function, 219 


GpiDeleteElementRange function, 219 
GpiDeleteMetaFile function, 219 
GpiDeletepalette function, 219 
GpiDeletesegment function, 220 
GpiDeletesegments function, 220 
GpiDeletesetld function, 220 
GpiDestoryps function, 220 
GpiDestroyRegion function, 220-221 
GpiDrawBits function, 221 
GpiDrawchain function, 221-222 
GpiDrawDynamics function, 222 
GpiDrawFrom function, 222 
GpiDrawsegment function, 222 
GpiElement function, 222-223 
GpiEndArea function, 223 
GpiEndElement function, 223 
GpiEndpath function, 223 
GpiEqualRegion function, 223-224 
GpiErase function, 224 
GpiErrorsegmentData function, 224 
GpiExcludeclipRectangle function, 224- 


225 


GpiFillpath function, 225 
GpiFloodFill function, 225-226 
GpiFrameRegion function, 226 
GpiFullArc function, 226 
GpiGetData function, 226-227 
Gpilmage function, 227 
GpilntersectclipRectangle function, 227- 


228 


GpiLabel function, 228 
GpiLine function, 228 
GpiLoadBitmap function, 228-229 
GpiLoadFonts function, 229 
GpiLoadMetaFile function, 229 
GpiLoadpublicFonts function, 229 
GpiMarker function, 229-230 
GpiModifypath function, 230 
GpiMove function, 230 
GpioffsetclipRegion function, 230 
GpioffsetElement function, 231 
GpioffsetRegion function, 231 
Gpiopensegment function, 231 
Gpioutlinepath function, 231-232 
GpipaintRegion function, 232 


RE . RERE 


GpipartialArc function, 232 
GpipathTORegion function, 233 
GpiplayMetaFile function, 233-234 
GpipointArc function, 234 
GpipolyFillet function, 234-235 
GpipolyFilletsharp function, 235 
Gpipolygons function, 235 
GpipolyLine function, 236 
GpipolyLineDisjoint function, 236 
GpipolyMaker function, 236 
Gpipolyspline function, 237 
Gpipop function, 237 
GpiptlnRegion function, 237 
Gpiptvisible function, 238 
GpiputData function, 238 
GpiQueryArcparams function, 238-239 
GpiQueryAttrMode function, 239 
GpiQueryAttrs function, 239 
GpiQueryBackcolor function, 239 
GpiQueryBackMix function, 240 
GpiQueryBitmapBits function, 240 
GpiQueryBitmapDimension function , 


240 


GpiQueryBitmapHandle function, 241 
GpiQueryBitmaplnfoHeader function , 


241 


GpiQueryBitmapparameters function , 


241 


GpiQueryBoundaryData function, 241 
GpiQueryBox function, 263 
GpiQuerycharAngle function, 241 
GpiQuerycharBox function, 242 
GpiQuerycharBreakEven function, 242 
GpiQuerycharDirection function, 242 
GpiQuerycharExtra function, 242 
GpiQuerycharMode function, 242-243 
GpiQuerycharset function, 243 
GpiQuerycharshear function, 243 
GpiQuerycharstringpos function, 243- 


244 


GpiQuerycharstringposAt function, 244 
GpiQueryclipBox function, 244 
GpiQueryclipRegion function, 245 
GpiQuerycolor function, 245 
GpiQuerycolorData function, 245 


GpiQuerycolorlndex function, 245-246 
GpiQuerycp function, 246 
GpiQuerycurrentposition function, 246 
GpiQueryDefArcparams function, 246 
GpiQueryDefAttrs function, 246 
GpiQueryDefaultviewMatrix function , 


247 


GpiQueryDefcharBox function, 247 
GpiQueryDefTag function, 247 
GpiQueryDefviewingLimits function , 


247 


GpiQueryDevice function, 247 
GpiQueryDeviceBitmapFormats 


function, 248 


GpiQueryDrawcontrol function, 248 
GpiQueryDrawingMode function, 248 
GpiQueryEditMode function, 248-249 
GpiQueryElement function, 249 
GpiQueryElementpointer function, 249 
GpiQueryElementType function, 249 
GpiQueryFacestring function, 250 
GpiQueryFontAction function, 250 
GpiQueryFontFileDescriptions function , 


250 


GpiQueryFontMetrics function, 250-251 
GpiQueryFonts function, 251 
GpiQueryFullFontFileDescs function , 


251 


GpiQueryGraphicsField function, 251 
GpiQuerylnitialsegmentAttrs function , 


251-252 


GpiQueryKerningpairs function, 252 
GpiQueryLineEnd function, 252 
GpiQueryLineJoin function, 252 
GpiQueryLineType function, 253 
GpiQueryLinewidth function, 253 
GpiQueryLinewidthGeom function, 253 
GpiQueryLogcolorTable function, 253- 


254 


GpiQueryLogicalFont function, 254 
GpiQueryMarker function, 254 
GpiQueryMarkerBox function, 254 
GpiQueryMarkerset function, 255 
GpiQueryMetaFileBits function, 255 
GpiQueryMetaFileLength function, 255 


GpiQueryMix function, 255-256 
GpiQueryModelTransformMatrix 


function, 256 


GpiQueryNearestcolor function, 256 
GpiQueryNumbersetlds function, 256 
GpiQuerypal function, 258 
GpiQuerypalette function, 257 
GpiQuerypalettelnfo function, 257 
GpiQuerypattern function, 257-258 
GpiQuerypatternRefpoint function, 258 
GpiQuerypatternset function, 258 
GpiQuerypickApertureposition function , 


259 


GpiQuerypickAperturesize function , 


259 


GpiQueryps function, 259 
GpiQueryRealcolors function, 259 
GpiQueryRegionBox function, 259-260 
GpiQueryRegionRects function, 260 
GpiQueryRGBColor function, 260 
GpiQueryseginentAttrs function, 261 
GpiQuerysegmentNames function, 261 
GpiQuerysegmentpriority function, 261- 


262 


GpiQuerysegmentTransformMatrix 


function, 262 


GpiQuerysetlds function, 262 
GpiQuerystopDraw function, 262 
GpiQueryTag function, 263 
GpiQueryTextAlignment function, 263 
GpiQueryviewingLimits function, 263 
GpiQueryviewingTransformMatrix 


function, 264 


GpiQueryviewport function, 256 
GpiQuerywidthTable function, 264 
GpiRectlnRegion function, 264 
GpiRectvisible function, 265 
GpiRemoveDynamics function, 265 
GpiResetBoundaryData function, 265 
GpiResetps function, 265-266 
GpiRestoreps function, 266 
GpiRotate function, 266 
GpisaveMetaFile function, 266 
Gpisaveps function, 267 
Gpiscale function, 267 


Gpiselectpalette function, 267 
GpisetArcparams function, 267 
GpisetAttrMode function, 267-268 
GpisetAttrs function, 268-269 
GpisetBackcolor function, 269 
GpisetBackMix function, 269 
GpisetBitmap function, 269-270 
GpisetBitmapDimension function, 270 
GpisetBitmapld function, 270-271 
GpisetBitmapsBits function, 2 70 
GpisetcharAngle function, 271 
GpisetcharBox function, 271 
GpisetcharBreakExtra function, 271 
GpisetcharDirection function, 271 
GpisetcharExtra function, 272 
GpisetcharMode function, 272 
Gpisetcharset function, 272 
Gpisetcharshear function, 272 
Gpisetclippath function, 272-273 
GpisetclipRegion function, 273 
Gpisetcolor function, 273 
Gpisetcp function, 273-274 
Gpisetcurrentposition function, 274 
GpisetDefArcparams function, 274 
GpisetDefAttrs function, 274-275 
GpisetDefTag function, 276 
GpisetDefviewingLimits function, 2 76 
GpisetDefviewMatrix function, 275-276 
GpisetDrawcontrol function, 276 
GpisetDrawingMode function, 276-277 
GpisetEditMode function, 277 
GpisetElementpointer function, 277 
GpisetElementpointerAthabel function , 


2:J7-2:J8 


GpisetGraphicsField function, 278 
GpisetlnitialsegmentAttrs function, 278 
GpisetLineEnd function, 278 
GpisetLineJoin function, 278-279 
GpisetLineType function, 279 
GpisetLinewidth function, 279 
GpisetLinewidthGeom function, 279 
GpisetMarker function, 279 
GpisetMarkerBox function, 280 
GpisetMarkerset function, 280 
GpisetMetaFileBits function, 280 


GpisetMix function, 280 
GpisEtModelTransformMatrix function , 


281 


Gpisetpageviewport function, 281 
GpisetpaletteEntries function, 281 
Gpisetpattern function, 282 
GpisetpatternRefpoint function, 282 
Gpisetpatternset function, 282 
Gpisetpel function, 282-283 
GpisetpickApertureposition function , 


283 


GpisetpickAperturesize function, 283 
Gpisetps function, 283 
GpisetRegion function, 284 
GpisetsegmentAttrs function , 284 
Gpisetsegmentpriority function, 284- 


285 


GpisetsegmentTransformMatrix 


function, 285 


GpisetTag function, 285 
GpisetTextAlignment function, 285~286 
GpisetviewingLimits function, 286 
GpisetviewingTransformMatrix 


function, 286 


GpistopDraw function, 285 
Gpistrokepath function, 286-287 
GpiTranslate function, 287 
GpiunloadFonts function, 287 
Gpiunloadpublic function, 287 
GpiwcBitBlt function, 287-288 
Graphics Programming Interface (GPI), 


206-288 


Graphics System Processor (GSP), 158- 


163 


GSP2COP instruction, 185 
GSP2GSP instruction, 185 
GSP2HOST instruction, 185 
GSP2HOSTXY instruction, 185 
GSP_CALLOC instruction, 184 
GSP_EXECUTE instruction, 184 
GSP_FREE instruction, 184 
GSP_MALLOC instruction, 184 
GSP_MAXHEAP instruction, 184 
GSP_MINIT instruction, 184 
GSP_REALLOC instruction, 184 


H 
HBAR command, 141 
HBBC command, 141 
HBBCHN command, 141 
HBBR command, 141 
HBBW command, 141 
HCBBW command, 141 
HCCHST command, 141 
HCHST command, 141 
HCLINE command, 141 
HCLOSE command, 141 
HCMRK command, 141 
HEAR command, 141 
HEGS command, 141 
HESC command, 141 
HINIT command, 141 
HINT command, 141 
HLDPAL command, 141 
HLINE command, 141 
HLT command, 71 
HMRK command, 141 
HOPEN command, 142 
HOST2GSP instruction, 185 
HOST2GSPXY instruction, 185 
HQCOORD command, 142 
HQCP command, 142 
HQDFPAL command, 142 
HQDPS command, 142 
HQMODE command, 142 
HQMODES command, 142 
HRCLINE command, 142 
HRECT command, 142 
HRLINE command, 142 
HRLPC command, 142 
HRPAL command, 142 
HSBCOL command, 142 
HSBP command, 142HSCMP 


command, 142 


HSCOL command, 142 
HSCOORD command, 142 
HSCP command, 142 
HSCS command, 142 
HSGQ command, 142 
HSHS command, 142 
HSLPC command, 142 


HSLT command, 142 
HSLW command, 142 
HSMARK command, 142 
HSMODE command, 142 
HSMX command, 142 
HSPAL command, 142 
HSPAIT command, 142 
HSPAITO command, 142 
HSYNC command, 142 
Hungarian notation, xvi-xvii 
HXIAIE command, 142 
HyperwriteA, 60-61 


I 
IDIV command, 64-65 
If command, 5 
IF..THEN..ELSE,13 
IMUL command, 65 
IN command, 69-70 
INC command, 65 
INC instruction,171 
Info command, 476 
INIT_PALET instruction, 186 
INIT_TEXT instruction, 186 
INS command, 84 
INSB command, 84 
INSD command, 89 
INSERT function, 29 
installation, compiler, 50-52 
INSTALL_ALM instruction, 186 
INSTALL_FONT instruction, 186 
INSTALL_PRIMITIVES instruction, 186 
INSTALL_RLM instruction, 186 
INSTALL_USERERROR instruction, 186 
instruction sets, 168-196 


34010, 168-176 
TIGA, 177-197 


instructions, REXX, 8 
INSW command, 84 
INT command, 67 
INTERPRET command, 17 
INTO command, 67 
INVD command, 97 
INVLPG command, 97 
IRET command, 67 


IRETD command, 99 
ITERATE command, 17 


J 
JA command, 67 
JAcc instruction,171-172 
JAE command, 67 
JB command, 67 
JBE command, 67 
JC command, 67 
JCXZ command, 67 
JE command, 67 
JECXZ command, 89 
JG command, 67 
JGE command, 67 
JL command, 67-68 
JLE command, 68 
JMP command, 68 
JNA command, 68 
JNAE command, 68 
JNB command, 68 
JNBE command, 68 
JNC command, 68 
JNE command, 68 
JNG command, 68 
JNGE command, 68 
JNL command, 68 
JNLE command, 68 
JNO command, 68 
JNP command, 68 
JNS command, 68 
JNZ command, 68-69 
JO command, 69 
JP command, 69 
JPE command, 69 
JPO command, 69 
JRcc instruction, 172 
JS command, 69 
JUMP instruction, 172 
JZ command, 69 


K 
KBD error codes, 541-571 
KBD functions, 376-384 


Kbdcharln function, 377-378 
Kbdclose function, 378 
KbdDeRegister function, 378 
KbdFlushBuffer function, 378-379 
KbdFreeFocus function, 379 
KbdGetcp function, 379 
KbdGetFocus function, 379 
KbdGetHWID function, 379-380 
KbdGetstatus function, 380-381 
Kbdopen function, 381 
Kbdpeek function, 381 
KbdRegister function, 381 
Kbdsetcp function, 382 
Kbdsetcustxt function, 382 
KbdsetFgnd function, 382 
Kbdsetstatus function, 382-383 
Kbdstringln function, 383 
Kbdsynch function, 383 
Kbdxlate function, 383-384 
keyboard and keys (see o`so mouse 


systems) 
application programming interface , 
355-392 
DOSDevloctl functions, 357-375 
KBD functions, 376-384 


L 
labels, REXX, 8-9 
LAHF command, 70 
LAR command, 84 
LASTPOS function, 29 
LDS command, 70 
LEA command, 70 
LEAVE command, 86 
LEFT function, 29 
LENGTH function, 29 
LES command, 70 
LFS command, 89 
LGDT command, 84 
LGS command, 90 
LIDT command, 84 
LINE instruction, 172 
LINEIN function, 29 
LINEOUT function, 29-30 


LINES function, 30 
LLDT command, 84 
LMO instruction, 172, 186 
LMSW command, 84 
Load command, 476 
LOADCOFF instruction, 187 
LOCK command, 71 
LODSB command, 72 
LODSD command, 93 
LODSW command, 72 
LOOP command, 69 
LOOPE command, 69 
looping,11-14 
LOOPNE command, 69 
LOOPNZ command, 69 
LOOPZ command, 69 
LSL command, 85 
LSS command, 90 
LTR command, 85 


M 
macros, REXX, 9-42 
math coprocessors, 81-83, 95-96 
math operators, 44 
MAX function, 30 
MCI (see media control interface) 
mciRXExit function, 482-483 
mciRXGetDeviceld function, 483 
mciRXGetErrorstring function, 483 
mciRxlnit function, 482 
mciRxsendstring function, 483 
media control interface (MCI), 472-488 


commands, 474-480 
using with REXX, 481-488 


memory, virtual, 527-528 
memory management, 507-528 


DOS functions, 508-524 


memory object, 527 
memory protection, 524-526 
menus, menuing system using REXX, 


45-47 


Micro Channel Architecture (MCA), 145 
MIN function, 30 
MMFM instruction, 173 


MMTM instruction, 173 
MODS instruction, 173 
MODU instruction, 173 
MOU error codes, 541-571 
MOU functions, 384-392 
Mouclose function, 385-386 
MouDeRegister function, 386 
MouDrawptr function, 386 
MouFlushQue function, 386 
MouGetDevstatus function, 386 
MouGetEventMask function, 387 
MouGetNumButtons function, 387 
MouGetNumMickeys function, 387 
MouGetNumQueEl function, 387 
MouGetptrpos function, 387-388 
MouGetptrshape function, 388 
MouGetscaleFact function, 388-389 
MoulnitReal function, 389 
Mouopen function, 389 
MouReadEventQue function, 389-390 
MouRegister function, 390 
MouRemoveptr function, 390-391 
MOU functions, 384-392 
mouse systems, 355-392 
MousetDevstatus function, 391 
MousetEventMask function, 391 
MousetptrLoc function, 391-392 
Mousetptrshape function, 392 
MousetscaleFact function, 392 
Mousynch function, 392 
MOV command, 70 
MOVB instruction, 173 
MOVE instruction, 173 
MOVI instruction, 173 
MOVK instruction, 173 
MOVSB command, 72 
MOVSD command, 93 
MOVSW command, 72 
MOVSX command, 90 
MOVX instruction, 173 
MOW instruction, 173 
MOVZX command, 90 
MPYS instruction, 173 
MPYU instruction, 173 
MUL command, 65 


multimedia API, 471-505 


media control interface, 472-488 
Ultimedia Toolkit, 488-505 


N 
NEG command, 65 
NEG instruction, 173 
NEGB instruction, 174 
NOP command,17, 71 
NOP instruction, 174 
NOT command, 65 
NOT instruction, 174 
NOT operator, 10 
NUMERIC DIGITS command, 17-18 
NUMERIC FORM command, 18 
NUMERIC FUZZ command, 18 


0 
Open command, 476-477 
operators, 9-10, 641-642 


REXX math, 44 


OPTIONS command, 18 
0R command, 65 
0R instruction, 174 
0R operator, 10 
0RI instruction, 174 
OUT command, 70 
0UTS command, 85 
0UTSB command, 85 
0UTSD command, 90 
0UTSW command, 85 
OVERLAY function, 30 


P 
PAGE_BUSY instruction, 187 
PAGE_FLIP instruction, 187 
parallel ports, 393-408 


loopback plug connections, 407 
pinouts, 406 


PARSE command, 18-19 
PATNFILL_CONVEX instruction , 


187 


PATNFILL_OVAL instruction, 187 
PATNFILL_PIEARC instruction, 187 


PATNFILL_POLYGON instruction, 187- 


188 


PATNFILL_RECT instruction, 188 
PATNFRAME_OVAL instruction, 188 
PATNFRAME_RECT instruction, 188 
PATNPEN_LINE instruction, 188 
PATNPEN_OVALARC instruction, 188 
PATNPEN_PIEARC instruction, 189 
PATNPEN_POINT instruction, 189 
PATNPEN_POLYLINE instruction, 189 
Pause command, 5, 477 
PDSK functions, 467-470 
PEEK_BREG instruction, 189 
Pentium processor, 97-101 
PEN_LINE instruction, 189 
PEN_OVAIARC instruction, 190 
PEN_PIEARC instruction, 190 
PEN_POINT instruction, 190 
PEN_POLYLINE instruction, 190 
Perfect Image/2, 495-499 
Performance Computer Diagnostics, 408 
PIXBLT instruction, 174 
PIXT instruction, 174 
Play command, 477 
PMATE (see Presentation Manager 


Automated Test Environment) 


PMREXX functions, 42-43 
POKE_BREG instruction, 190 
POP command, 70 
POPA command, 85 
POPAD command, 90 
POPF command, 70 
POPFD command, 90 
POPST instruction, 174 
ports, parallel and serial, 393-408 
POS function, 30 
Presentation Manager (PM), error codes, 


572-612 


Presentation Manager Automated Test 


Environment (PMATE), 55-61 


processor commands, 63-101 
processor protection rings, 525 
production tools, 56-58 
Profession Developer Kit (PDK), 3 
programs and programming 


editors, 59-61 
menuing system, 45-47 
optimizing environment, 49-52 
production tools, 56-58 
REX, 43-47 
REXX MCI source code, 483-487 


Protshell command, 5 
PULL command, 19 
PUSH command, 19, 70 
PUSHA command, 85 
PUSHAD command, 90 
PUSHED command, 90 
PUSHST instruction, 174PUTST 


instruction, 175 


Q 
QUEUE command, 20 
QUEUED function, 30 


Ft 
RANDOM function, 30 
RCL command, 65 
RCR command, 66 
RDMSR command, 99 
Record command, 477 
registers 


34010 input/output, 164-167 
34010 status, 161-162 
8514/A, 143-145 
advanced function control, 150 
aperture control, 202 
aperture index, 203 
background mix, 154-155 
display control, 148 
foreground mix, 155-156 
graphics processor status/command, 


150-152 
index, 204-206 
interrupt enable, 202 
interrupt status, 202 
memory accessmode, 204 
memory control, 157 
operating mode, 201 
pixel control, 158 


ROM page select, 150 
SSV transfer register, 153-154 
subsystem status/control register, 149- 


150 


TMS34010 file 8 functions, 160-161 
virtual memory control, 203 
virtual memory interrupt status, 203 
XGA, 201 


Release command, 477-478 
REM command, 5 
REP command, 72 
REPE command, 72 
REPNE command, 72 
REPNZ command, 72 
REPZ command, 72 
Resume command, 478 
RET command, 69 
RETI instruction, 175 
RETS N instruction, 175 
RETURN command, 20 
REV instruction, 175 
REVERSE function, 31 
REXX, 6-47 


command files, 6-9 
commands, 15-22 
control structures, 10-14 
functions, 22-42 
macro language, 9-42 
programming, 43-47 
using MCI with, 481-488 


RIGHT function, 31 
RL instruction, 175 
RMO instruction, 191 
ROL command, 66 
ROR command, 66 
RSM command, 99 
BXFUNCADD function, 31 
RXFUNCDROP function, 31 
RXFUNCQUERY function, 31 
RXMESSAGEBOX function, 42-43 
RXQUEUE function, 31-32 


S 
SAHF command, 70 


SAL command, 66 
SAR command, 66 
Save command, 478 
SAY command, 20 
SBB command, 65 
SCASB command, 72-73 
SCASD command, 93 
SCASW command, 73 
security, memory protection, 524-526 
SEED_FILL instruction, 191 
SEED_PATNFILL instruction, 191 
Seek command, 478 
segment start address (SSA), 163 
SELECT..WHEN..OTHERWISE,14 
SELECT_FONT instruction, 191 
serial ports, 393-408 


loopback plug connections, 408 
pinouts, 407 


Set command, 478-480 
SETA command, 90 
SETAE command, 90 
SETB command, 90 
SETBE command, 90-91 
SETC command, 91 
SETC instruction, 175 
SETE command, 91 
SETF instruction, 175 
SETG command, 91 
SETGE command, 91 
SETINGE command, 92 
SETL command, 91 
SETLE command, 91 
SetLocal command, 5 
SETNA command, 91 
SETNAE command, 91SETNB 


command, 91 


SETNBE command, 91 
SETNC command, 91 
SETNE command, 91 
SETNG command, 91 
SETNL command, 92 
SETNLE command, 92 
SETNO command, 92 
SETNP command, 92 
SETNS command, 92 


SETNZ command, 92 
SETO command, 92 
SETP command, 92 
SETPE command, 92 
SETPO command, 92 
SETS command, 92 
SETZ command, 92 
SET_BCOLOR instruction, 191 
SET_CLIP_RECT instruction, 191 
SET_COLORS instruction, 191 
SET_CONFIG instruction, 191 
SET_CURS_SHAPE instruction, 192 
SET_CURS_STATE instruction, 192 
SET_CURS_XY instruction, 192 
SET_DRAW_ORIGIN instruction, 192 
SET_DSTBM instruction, 192 
SET_FCOLOR instruction, 193 
SET_INTERRUPT instruction, 193 
SET_PALET instruction, 193 
SET_PALET_ENTRY instruction, 193 
SET_PATN instruction, 193 
SET_PENSIZE instruction, 193 
SET_PMASK instruction, 193 
SET_PPOP instruction, 193-194 
SET_SRCBM instruction, 194 
SET_TEXTAITR instruction, 194 
SET_TIMEOUT instruction, 194 
SET_TRANSP instruction, 194 
SET_VECTOR instruction, 194 
SET_VIDEOMODE instruction, 194 
SET_WINDOWING instruction, 195 
SET_WKSP instruction, 195 
SEXT instruction, 175 
SGDT command, 85 
Shell command, 5 
Shift command, 5 
SHL command, 66 
SHLD command, 89 
SHR command, 66 
SHRD command, 89 
SIDT command, 85 
SIGN function, 32 
SIGNAL command, 20 
Simonyi, Charles, xvi 
SLA instruction, 175 


SLDT command, 85 
SlickEdit, 59 
SLL instruction, 175 
SMSW command, 85 
SOURCELINE function, 32 
SPACE function, 32 
SRA instruction, 175 
SRL instruction, 176 
Status command, 480 
STC command, 71 
STD command, 71 
STI command, 71 
STOSB command, 73 
STOSD command, 93 
STOSW command, 73 
STR command, 85 
STREAM function, 32 
strings 


Codeview, 643 
REXX, 7 


STRIP function, 33 
SrvLED_LINE instruction, 195 
SUB command, 65 
SUB instruction, 176 
SUBB instruction, 176 
SUBI instruction, 176 
SUBK instruction, 176 
SUBSTR function, 33 
SUBWORD function, 33 
SUBXY instruction, 176 
SWAP_BM instruction, 195 
SYMBOL function, 33 
symbols, Codeview, 642 
SYNCHRONIZE instruction, 196 
SYSCLS function, 33 
SYSCREATEOBJECT function, 33 
SYSCURPOS function, 34 
SYSCURSIAIE function, 34 
SYSDEREGISTEROBJECTCIASS 


function, 34 


SYSDRIVEINF function, 34 
SYSDRIVEMAP function, 34 
SYSDROPFUNCS function, 35 
SYSFILEDELETE function, 35 
SYSFILESEARCH function, 35 


SYSFILETREE function, 35-36 
SYSGETEA function, 36 
SYSGETKEY function, 36 
SYSGETMESSAGE function, 37 
SYSMKDIR function, 37 
SYSOS2VER function, 37 
SYSPUTEA function, 37 
SYSQUERYCLASSLIST function, 37 
SYSREGISTEROBJECTCLASS 


function, 38 


SYSRMDIR function, 38 
SYSSEARCHPATH function, 38 
SYSSETICON function, 38 
SYSSLEEP function, 38 
System Management Mode (SMM), 98 
SYSTEMPFILENAME function, 38-39 
SYSTEXTSCREENREAD function, 39 
SYSTEXTSCREENSIZE function, 39 
SYSWAITNAMEDPIPE function, 39 


T 
TEST command, 66 
testing 


applications, 52-54 
Presentation Manager environment 
for, 55-61 


Texas Instruments Graphics Architecture 


(TIGA), instruction set, 177-197 


TEXT_OUT instruction, 196 
TEXT_WIDTH instruction, 196 
TIME function, 40 
Tiny, 59 
Toggle State File (TSF), 619 
TRACE command, 21-22 
TRACE function, 40 
TRANSLATE function, 40 
TRANSP_OFF instruction, 196 
TRANSP_ON instruction, 196 
TRAP N instruction, 176 
TRUNC function, 40-41 


U 
Ultimedia Toolkit, 488-505 


Builder/2, 489-494 


Perfect Image/2, 495-499 
Workplace/2, 499-505 


V 
VALUE function, 41 
variables, naming conventions, xviii- 


REH 


VERIFY function, 41 
VERR command, 86 
VERW command, 86 
video API, 102-354 


8514/A AI commands, 141-142 
display modes, 137-140 
Graphics Programming Interface, 206- 
288 
instruction sets, 168-196 
registers, 143-167, 201-206 
VIO functions, 103-136 
WIN functions, 288-354 


Video Electronics Standards Association 


OVESA), 137, 199 


video input/output (see VIO) 
VIO error codes, 541-571 
VIO functions, 103-136 
VioAssociate function, 104 
ViocreateLogFont function, 104-105 
Viocreateps function, 105 
VioDeletesetld function, 105 
VioDeRegister function, 111 
VioDestroyps function, 105 
VioEndpopup function,111 
VioGetAnsi function,111 
VioGetBuf function, 111-112 
VioGetconfig function,112-114 
VioGetcp function,114 
VioGetcurpos function,114 
VioGetcurType function,114-115 
VioGetDevicecellsize function, 105 
VioGetFont function, 115-116 
VioGetMode function,116-117 
VioGetorg function, 106 
VioGetphysBuf function, 117-118 
VioGetstate function,118-119 
VioGlobalReg function, 120-121 


VioModeundo function, 121 
VioModewait function, 121-122 
Viopopup function, 122 
Vioprtsc function, 122 
VioprtscToggle function, 122-123 
VioQueryFonts function, 106-109 
VioQuerysetlds function, 109 
VioReadcellstr function, 123 
VioReadcharstr function, 123 
VioRegister function, 123-125 
ViosavRedraw function, 125 
ViosavRedrawwait function, 125-126 
VioscrLock function, 126 
VioscrollDn function, 126 
VioscrollLf function, 127 
VioscrollRt function, 127 
Vioscrollup function, 127-128 
VioscrunLock function, 128 
ViosetAnsi function, 128 
Viosetcp function, 128-129 
Viosetcurpos function, 129 
ViosetcurType function, 129-130 
ViosetDevicecellsize function, 109 
ViosetFont function, 130 
ViosetMode function, 130-132, 136 
Viosetorg function, 109 
Viosetstate function, 132-133 
VioshowBuf function, 134 
Vioshowps function, 109 
Viowrtcellstr function, 134 
Viowrtcharstr function, 134 
ViowrtcharstrAtt function, 134-135 
ViowrtNAttr function, 135 
ViowrtNcell function, 135 
ViowrtNchar function, 135-136 
ViowrtTTY function, 136 
virtual memory, 527-528 


W 
WAIT command, 71 
WAIT_SCAN instruction, 196 
WBINVD command, 97 
WIN functions, 288-354 
WinAddAtom function, 289 


WinAddswitchEntry function, 289-290 
WinAlarm function, 290 
WinAssoicateHelplnstance function, 290 
WinBeginEnumwindows function, 290 
WinBeginpaint function, 290-291 
WinBroadcastMsg function, 291 
WincalcFrameRect function, 291 
WincallMsgFilter function, 291 
Wincancelshutdown function, 291 
WinchangeswitchEntry function, 291- 


292 


WincheckButton function, 292 
WincheckMenultem function, 292 
Wincloseclipbrd function, 292 
Wincomparestrings function, 292 
WincopyAccelTable function, 292-293 
WincopyRect function, 293 
WincpTranslatechar function, 293 
WincpTranslatestring function, 293 
WincreateAccelTable function, 293 
WincreateAtomTable function, 293 
Wincreatecursor function, 294 
WincreateDlg function, 294 
WincreateFramecontrols function, 294 
WincreateHelplnstance function, 295 
WincreateHelpTable function, 295 
WincreateMenu function, 295 
WincreateMsgQueue function, 295 
Wincreateobject function, 295-296 
Wincreatepointer function, 296-297 
Wincreatepointerlndirect function, 297 
Wincreatestdwindow function, 297 
WincreateswitchEntry function, 297- 


298 


Wincreatewindow function, 298 
WinDdelnitiate function, 298 
WinDdepostMsg function, 298-299 
WinDdeRespond function, 299 
WinDefDlgproc function, 299 
WinDefFileDlgproc function, 299 
WinDefFontDlgproc function, 299 
WinDefwindowproc function, 299 
WinDeleteAtom function, 300 
WinDeletedLibrary function, 300 
WinDeleteLboxltem function, 300 


WinDeleteprocedure function, 300 
WinDeregisterobjectclass function, 300 
WinDestroyAccelTable function, 300 
WinDestroyAtomTable function, 300- 


301 


WinDestroycursor function, 301 
WinDestroyMsgQueue function, 301 
WinDestroyobject function, 301 
WinDestroypointer function, 301 
WinDestroywindow function, 301 
WinDismissDlg function, 301-302 
WinDispatchMsg function, 302 
WinDlgBox function, 302 
WinDrawBitmap function, 302 
WinDrawBorder function, 303 
WinDrawpointer function, 303 
WinDrawText function, 303 
WinEmptyclipboard function, 304 
WinEnablecontrol function , 304 
WinEnableMenultem function, 304 
WinEnablephyslnput function, 304 
WinEnablewindow function, 304 
WinEnablewindowupdate function, 304 
WinEndEnumwindows function, 305 
WinEndpaint function, 305 
WinEnumclipbrdFmts function, 305 
WinEnumDlgltem function, 305 
WinEnumobjectclasses function, 305 
WinEqualRect function, 305 
WinExcludeupdateRegion function, 306- 


307 


WinFiledlg function, 306 
WinFillRect function, 306 
WinFindAtom function, 306 
WinFlashwindow function, 306-307 
WinFocuschange function, 307 
WinFontDlg function, 307 
WinFreeErrorlnfo function, 307 
WinFreeFileDlgList function, 307 
WinFreeFilelcon function, 307 
WinGetclipps function, 307-308 
WinGetcurrentTime function, 308 
WinGetDlgMsg function, 308 
WinGetErrorlnfo function, 308 
WinGetKeystate function, 308 


WinGetLastError function, 308-309 
WinGetMaxposition function, 309 
WinGetMinposition function, 309 
WinGetMsg function, 309 
WinGetNextwindow function, 309 
WinGetphysKeystate function, 309 
WinGetps function, 309-310 
WinGetscreenps function, 310 
WinGetsysBitmap function, 310 
WinlnflateRect function, 311 
Winlnitialize function, 311 
WinlnsendMsg function, 311 
WinlnsertLboxltem function, 311 
WinlntersectRect function, 311 
WinlnvalidateRect function, 311 
WinlnvalidateRegion function, 311-312 
WinlnvertRect function, 312 
Winlschild function, 312 
WinlscontrolEnabled function, 312 
WinlsMenuchecked function, 312 
WinlsMenuEnabled function, 312 
WinlsMenultemvalid function, 312 
WinlsphyslnputEnabled function, 312 
WinlsRectEmpty function, 313 
WinlsThreadActive function, 313 
Winlswindow function, 313 
WinlswindowEnabled function, 313 
Winlswindowshowing function, 313 
Winlswindowvisible function, 313 
WinLoadAccelTable function, 313 
WinLoadDlg function, 314 
WinLoadFilelcon function, 314 
WinLoadHelpTable function, 314 
WinLoadLibrary function, 314 
WinLoadMenu function, 314 
WinLoadMessage function, 315 
WinLoadpointer function, 315 
WinLoadprocedure function, 315 
WinLoadstring function, 315 
WinLockvisRegions function, 315 
WinLockwindowupdate function, 316 
WinMakepoints function, 316 
WinMakeRect function, 316 
WinMapDlgpoints function, 316 
WinMapwindowpoints function, 316 


WinMessageBox function, 317 
WinMultwindowFromlDs function, 317 
WinNextchar function, 318 
WinoffsetRect function, 318 
Winopenclipbrd function, 318 
WinopenwindowDC function, 318 
WinpeekMsg function, 318 
WinpopupMenu function, 318-319 
WinpostMsg function, 319 
WinpostQueueMsg function, 319 
Winprevchar function, 319 
WinprocessDlg function, 319-320 
WinptlnRect function, 320 
WinQueryAccelTable function, 320 
WinQueryActivewindow function, 320 
WinQueryAnchorBlock function, 320 
WinQueryAtomLength function, 320 
WinQueryAtomName function, 321 
WinQueryAtomusage function, 321 
WinQueryButtoncheckstate function , 


321 


WinQuerycapture function, 321 
WinQueryclasslnfo function, 321 
WinQueryclassName function, 322 
WinQueryclassThunkproc function, 322 
WinQueryclipbrdData function, 322 
WinQueryclipbrdFmtlnfo function, 322 
WinQueryclipbrdowner function, 322 
WinQueryclipbrdviewer function, 322 
WinQuerycp function, 322-323 
WinQuerycpList function, 323 
WinQuerycursorlnfo function, 323 
WinQueryDesktopBkgnd function, 323 
WinQueryDesktopwindow function, 323 
WinQueryDlgltemshort function, 323- 


324 


WinQueryDlgltemText function, 324 
WinQueryDlgTextLength query, 324 
WinQueryFocus function, 324 
WinQueryHelplnstance function, 324 
WinQueryLboxcount function, 324 
WinQueryLboxltemText function, 324- 


325 


WinQueryLboxltemTextLength function , 


325 


WinQueryLboxselectedltem function , 


325 


WinQueryMsgpos function, 325 
WinQueryMsgTime function, 325 
WinQueryobject function, 325 
WinQueryobjectwindow function, 325 
WinQuerypointer function, 325 
WinQuerypointerlnfo function, 325-326 
WinQuerypointerpos function, 326 
WinQuerypresparam function, 326 
WinQueryQueuelnfo function, 326 
WinQueryQueuestatus function , 326~ 


327 


WinQuerysessionTitle function, 327 
WinQueryswitchEntry function, 327 
WinQueryswitchHandle function, 32 7 
WinQueryswitchList function, 32 7 
WinQuerysyscolor function, 327 
WinQuerysysModalwindow function , 


327-328 


WinQuerysyspointer function, 328 
WinQuerysystemAtomTable function , 


328 


WinQuerysysvalue function, 328-329 
WinQueryTasksizepos function, 329 
WinQueryTaskTitle function, 329 
WinQueryupdateRect function, 329 
WinQueryupdateRegion function, 329- 


330 


WinQueryversion function, 330 
WinQuerywindow function, 330 
WinQuerywindowDC function, 330 
WinQuerywindowModel function, 330- 


331 


WinQuerywindowpos function, 331 
WinQuerywindowprocess function, 331 
WinQuerywindowptr function, 331 
WinQuerywindowRect function, 331 
WinQuerywindowText function, 331- 


332 


WinQuerywindowTextLength function , 


332 


WinQuerywindowThunkproc function , 


332 


WinQuerywindowuLong function, 332 


WinQuerywindowushort function , 332 
WinRealize function, 333 
WinRegisterclass function, 333 
WinRegisterobjectclass function, 333 
WinRegisteruserDatatype function, 333- 


335 


WinRegisteruserMsg function, 335 
WinReleaseHook function, 335 
WinReleaseps function, 335-336 
WinRemovepresparam function, 336 
WinRemoveswitchEntry function, 336 
WinReplaceobjectclass function, 336 
WinRequestMutexsem function, 336 
WinRestorewindowpos function, 336- 


337 


Winsavewindowpos function, 337 
Winscrollwindow function, 337 
WinsendDlgltemMsg function, 337 
WinsendMsg function, 338 
WinsetAccelTable function, 338 
WinsetActivewindow function, 338 
Winsetcapture function, 338 
WinsetclassMsglnterest function, 339 
WinsetclassThunkproc function, 339 
WinsetclipbrdData function, 339 
Winsetclipbrdowner function, 339 
Winsetclipbrdviewer function, 340 
Winsetcp function, 340 
WinsetDesktopBkgnd function, 340 
WinsetDlgltemshort function, 340 
WinsetDlgltemText function, 340-341 
WinsetFilelcon function, 341 
WinsetFocus function, 341 
WinsetHook function, 341 
WinsetKeyboardstateTable function , 


341-342 


WinsetLboxltemText function , 342 
WinsetMenultemText function, 342 
WinsetModalwindow function, 345 
WinsetMsglnterest function , 342 
WinsetMsgMode function, 342 
WinsetMultwindowpos function, 342- 


343 


WinsetobjectData function, 343 
Winsetowner function, 343 


Winsetparent function, 343 
Winsetpointer function, 343 
Winsetpointerpos function, 344 
Winsetpresparam function, 344 
WinsetRect function, 344 
WinsetRectEmpty function, 344 
WinsetsynchroMode function, 344 
Winsetsyscolors function, 344-345 
Winsetsysvalue function, 346 
Winsetwindowpos function, 346-347 
Winsetwindowptr function, 347 
WinsetwindowsBits function, 346 
WinsetwindowText function, 347 
WinsetwindowThunkproc function, 347 
WinsetwindowuLong function, 347 
Winsetwindowushori function, 348 
Winshowcursor function, 348 
Winshowpointer function, 348 
WinshowTrackRect function, 348 
Winshowwindows function, 348 
Winshutdownsystem function, 349 
WinstartApp function, 349 
WinstartTimer function, 349 
WinstopTimer function, 349 
Winstorewindowpos function, 349-350 
Winsubclasswindow function, 350 
Winsubstitutestrings function, 350 
WinsubtractRect function, 350 
WinswitchToprogram function, 350 
WinTerminate function, 351 
WinTerminateApp function, 351 
WinTrackRect function, 351 
WinTranslateAccel function, 351 
WinunionRect function, 351 
Winupdatewindow function, 351-352 
Winupper function, 352 
Winupperchar function, 352 
WinvalidateRect function, 352 
WinvalidateRegion function, 352-353 
WinwaitEventsem function, 353 
WinwaitMsg function, 353 
WinwaitMuxwaitsem function, 353 
WinwindowFromDC function, 353 
WinwindowFromlD function, 353-354 
WinwindowFrompoint function, 354 


WORD function, 41 
WORDINDEX function, 41 
WORDLENGTH function, 41 
WORDPOS function, 41 
WORDS function, 42 
Workplace Shell WPS), 2-3, 47-49 
Workplace/2, 499-505 
WRMSR command, 100 


X 
X2B function, 42 
X2C function, 42 
X2D function, 42 


RADD command, 96 
XCHG command, 70 
XGA (see Extended Graphics Array) 
XLAT command, 71 
XOR command, 66 
XOR instruction, 176 
XORI instruction, 176 
XRANGE function, 42 


Z 
ZEXT instruction, 176 
ZOOM_RECT instruction, 196 
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